Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
JSON write-back prevention guard
Run from server/: node_modules/.bin/vitest run jsonWritebackConventions.test.js.
The guard parses service source only; it never imports services, reads runtime
records, connects to a database, or requires git history to run.
A direct readJSONFile call and atomicWrite call with the same normalized
first argument in the same service module require either statically strict reads
or an explicit lifecycle exception in jsonWritebackExceptions.js. New pairs
fail as unclassified; removed/strict-converted pairs fail as stale exceptions.
Every exception records why a fallback cannot overwrite durable records. Review
that reason against the caller whenever the lifecycle changes. This is a review
inventory guard, not a proof that all exceptional control flow remains safe.
Raw reads feeding safeJSONParse (#12440)
tryReadFile and readFile collapse "unreadable" into "absent" (or throw), and
safeJSONParse turns malformed text into the caller's default. A raw read whose
bytes reach safeJSONParse, through a variable in the same lexical scope (or an enclosing
one; parameters and inner declarations shadow) or inline in its first argument, therefore counts as a non-strict
read of that read's path and pairs with a same-path atomicWrite exactly like
readJSONFile. tryReadFileStrict is strict and never counted. A raw read that
never reaches a parse (a text file, a hash) is not a candidate. Convert a hit to
tryReadFileStrict / readJSONFileStrict (ENOENT initializes; anything else
refuses the write), or classify it in jsonWritebackExceptions.js with the reason
the fallback cannot destroy durable data, or an issue that tracks the conversion.
Worked examples: digital-twin-meta.js, genome.js and cosAgentIndex.js.
Syntax and limits
Babel parses real call expressions, including nested arguments, options and
calls inside template interpolations. Comments and strings describing calls do
not count. Path tokens ignore formatting and comments, normalize string quotes,
and preserve literal contents. Keys contain no positions. Literal strict: true
in the third argument and readJSONFileStrict are strict. A subsequent spread,
computed key, or false/unknown strict property invalidates that proof; an earlier
spread followed by literal strict:true is safe. Mixed strict/non-strict reads of
one path still require classification. Dynamic strict options require manual
caller review, including the strict defaults in Ask and POST run storage.
This is deliberately same-expression, same-module syntax matching, not whole-program dataflow. It recognizes direct names and named import aliases; it does not resolve scopes/shadowing, namespace calls, wrapper functions, aliased path variables, equivalent path-building expressions, or different parameter names across functions. Same-name locals in unrelated functions can be false positives. A changed expression can therefore leave this scanner's coverage; the stale-entry failure calls attention to existing exceptions that move. There is no blanket module exemption and no assertion that 79 modules represent every JSON lifecycle in PortOS.
The sibling audits explicitly checked paths outside exact-expression matching:
- Alcohol/Nicotine daily logs go through
loadDailyLogandreadLocalDailyLog; all mutation callers pass strict:true. MortalLoom response summaries are read-only, and its imported destination aliases are preflighted strictly. - Ask's
pathFor(conversationId)mutation andpathFor(id)listing share a strict-by-default loader; only aggregation opts out and skips null records. - Daily review history uses
reviewDate, while confirmation usesdateand a strict loader. These expressions deliberately do not compare equal. - Sprite generation, candidate listing, approval, runtime pointers and run records use different local aliases. The media audit made mutable provenance, geometry and approval reads strict; source/projection-only fallbacks stay documented beside their calls. Candidate sidecars use new generated names.
- Sharing import/export reads include transport input and local merge-target aliases; the sync audit hardened the destination reads and annotation sources.
- MeatSpace's goals birth-date mirror gained a same-expression pair during the personal audit. It is an additional registry entry beyond the original 94: migration skips unreadable input, and mirror mutation preflights strictly.
Baseline reconciliation
Historical audit at d7e2fb47d: 79 modules, 94 path pairs. All seven sibling
PR classifications were reconciled with their merged source. 73 original
pairs now read strictly; 21 remain explicitly classified, plus the additional
MeatSpace goals pair above (22 current exceptions). The registry gives the
concrete cache, authoritative-rebuild, or no-unsafe-write-back reason for each.
The table is a historical audit record, not a generated manifest or a fixed
allowlist of modules. Future service pairs are discovered directly at test time.
| Service module | Normalized path expression | Disposition after audits | Classification PR |
|---|---|---|---|
| agentRunReconciler.js | path |
Reviewed exception (see registry) | #6980 |
| agentRunTracking.js | metaPath |
Reviewed exception (see registry) | #6980 |
| albums/file.js | ALBUMS_FILE |
Strict read | #6984 |
| appleHealthIngest.js | filePath |
Strict read | #6981 |
| artists/file.js | ARTISTS_FILE |
Strict read | #6984 |
| askConversations.js | pathFor ( id ) |
Reviewed exception (see registry) | #6983 |
| authors/file.js | AUTHORS_FILE |
Strict read | #6984 |
| autobiography.js | CONFIG_FILE |
Strict read | #6981 |
| autobiography.js | STORIES_FILE |
Strict read | #6981 |
| autonomousJobs/store.js | JOBS_FILE |
Strict read | #6980 |
| backup.js | STATE_PATH |
Strict read | #6982 |
| backup.js | manifestPath |
Reviewed exception (see registry) | #6982 |
| bibleStore.js | filePath ( workId ) |
Strict read | #6983 |
| brainJournal.js | OBSIDIAN_LOCATIONS_FILE |
Strict read | #6981 |
| brainParity.js | REPORTS_FILE |
Strict read | #6981 |
| calendarAccounts.js | ACCOUNTS_FILE |
Strict read | #6978 |
| character.js | CHARACTER_FILE |
Strict read | #6981 |
| claudeChangelog.js | STATE_FILE |
Reviewed exception (see registry) | #6978 |
| creative/creativeRunLedger.js | file |
Strict read | #6983 |
| dailyDriver.js | FILE |
Strict read | #6981 |
| dailyReview.js | join ( REVIEW_DIR , ` ${ date } .json ` ) |
Strict read | #6981 |
| dataSync.js | CHARACTER_FILE |
Strict read | #6982 |
| dataSync.js | GOALS_FILE |
Strict read | #6982 |
| dataSync.js | filePath |
Strict read | #6982 |
| datadog.js | DATADOG_CONFIG_FILE |
Strict read | #6978 |
| digital-twin-sync.js | TASTE_FILE |
Strict read | #6981 |
| digital-twin-sync.js | path |
Strict read | #6981 |
| featureAgents.js | FA_FILE |
Strict read | #6980 |
| github.js | REPOS_FILE |
Strict read | #6978 |
| goalCalendarScheduler.js | GOALS_FILE |
Strict read | #6981 |
| imageTo3d/sourceKeying.js | preparedCacheMetadataPath ( targetPath ) |
Reviewed exception (see registry) | #6979 |
| insightsService.js | NARRATIVE_FILE |
Reviewed exception (see registry) | #6981 |
| insightsService.js | THEMES_FILE |
Reviewed exception (see registry) | #6981 |
| maintenanceRun.js | runsFile ( ) |
Strict read | #6980 |
| meatspace.js | CONFIG_FILE |
Strict read | #6981 |
| meatspaceAlcohol.js | CUSTOM_DRINKS_FILE |
Strict read | #6981 |
| meatspaceCalendar.js | ACTIVITIES_FILE |
Strict read | #6981 |
| meatspaceCalendar.js | EVENTS_FILE |
Strict read | #6981 |
| meatspaceNicotine.js | CUSTOM_PRODUCTS_FILE |
Strict read | #6981 |
| meatspacePost.js | CONFIG_FILE |
Strict read | #6981 |
| meatspacePostMemory.js | MEMORY_ITEMS_FILE |
Strict read | #6981 |
| meatspacePostMorse.js | MORSE_FILE |
Strict read | #6981 |
| meatspacePostReview.js | REVIEW_SCHEDULE_FILE |
Strict read | #6981 |
| mediaAnnotations.js | STATE_PATH |
Strict read | #6979 |
| mediaSketches.js | jsonPathFor ( key ) |
Reviewed exception (see registry) | #6979 |
| modelPersonality.js | resultsFile ( ) |
Strict read | #6980 |
| mortalLoomStore.js | goalsPath |
Strict read | #6981 |
| mortalLoomStore.js | localPath |
Strict read | #6981 |
| obsidian.js | VAULTS_FILE |
Strict read | #6978 |
| peerUsage.js | PEER_USAGE_FILE |
Strict read | #6982 |
| pipeline/continuityBible.js | ledgerPath ( seriesId ) |
Strict read | #6983 |
| pipeline/editorialScore.js | ledgerPath ( seriesId ) |
Strict read | #6983 |
| pipeline/manuscriptComments.js | reviewPath ( seriesId ) |
Strict read | #6983 |
| pipeline/reverseOutline.js | outlinePath ( seriesId ) |
Strict read | #6983 |
| postRunStore.js | SESSIONS_FILE |
Reviewed exception (see registry) | #6981 |
| postRunStore.js | TRAINING_FILE |
Reviewed exception (see registry) | #6981 |
| projectFileStore.js | file |
Strict read | #6983 |
| providerQuotaShare.js | PROVIDER_QUOTAS_FILE |
Reviewed exception (see registry) | #6982 |
| rounds.js | STATE_PATH |
Strict read | #6980 |
| sharing/annotationsSync.js | recordPath |
Strict read | #6982 |
| sharing/buckets.js | REGISTRY_PATH ( ) |
Strict read | #6982 |
| sharing/buckets.js | bucketJsonPath |
Reviewed exception (see registry) | #6982 |
| sharing/exporter.js | bucketBlobIndexPath ( bucketPath ) |
Reviewed exception (see registry) | #6982 |
| sharing/importer.js | inboxPath ( bucketId ) |
Strict read | #6982 |
| sharing/importer.js | persistedPath |
Strict read | #6982 |
| sharing/manifest.js | cursorPath ( bucketId ) |
Strict read | #6982 |
| sharing/manifest.js | join ( bucketPath , "manifests" , filename ) |
Reviewed exception (see registry) | #6982 |
| sharing/subscriptions.js | STATE_PATH ( ) |
Strict read | #6982 |
| sprites/atlas.js | join ( dir , RUNTIME_POINTER_REL ) |
Strict read | #6979 |
| sprites/localAnimationJobHook.js | recordPath |
Strict read | #6979 |
| sprites/publish.js | join ( dir , RUNTIME_PUBLICATIONS_REL ) |
Strict read | #6979 |
| sprites/recordsFile.js | RECORDS_FILE |
Strict read | #6979 |
| sprites/reference.js | join ( candidatesDir , ` ${ name . replace ( /.png$/ , "" ) } .generation.json ` ) |
Reviewed exception (see registry) | #6979 |
| sprites/walk.js | join ( spriteDir ( recordId ) , selectionRelPath ( recordId ) ) |
Strict read | #6979 |
| sprites/walk.js | join ( spriteDir ( recordId ) , walkSetRelPath ( recordId ) ) |
Strict read | #6979 |
| syncOrchestrator.js | CURSORS_FILE |
Strict read | #6982 |
| taskScheduleStore.js | SCHEDULE_FILE |
Strict read | #6980 |
| taskTemplates.js | TEMPLATES_FILE |
Strict read | #6980 |
| tools.js | toolPath ( id ) |
Reviewed exception (see registry) | #6978 |
| tracks/file.js | TRACKS_FILE |
Strict read | #6984 |
| twinEnrichment.js | CHRONOTYPE_OBSERVED_FILE |
Reviewed exception (see registry) | #6981 |
| twinEnrichment.js | TASTE_OBSERVED_FILE |
Strict read | #6981 |
| updateChecker.js | UPDATE_FILE |
Strict read | #6978 |
| usageBackfill.js | correction . metadataPath |
Reviewed exception (see registry) | #6980 |
| usageReconciler.js | metadataPath |
Reviewed exception (see registry) | #6980 |
| userActions.js | eventsFile ( ) |
Strict read | #6981 |
| videoTimeline/local.js | PROJECTS_FILE |
Strict read | #6984 |
| voice/timers.js | STORE_PATH |
Strict read | #6980 |
| weeklyDigest.js | path |
Reviewed exception (see registry) | #6981 |
| workspaceContext.js | CONTEXTS_FILE |
Strict read | #6980 |
| writersRoom/store.js | wrExercisesFile ( ) |
Strict read | #6984 |
| writersRoom/store.js | wrFoldersFile ( ) |
Strict read | #6984 |
| youtubeIngest.js | INDEX_FILE |
Strict read | #6979 |