Skip to content

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

17.0 KB
Raw Blame

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 loadDailyLog and readLocalDailyLog; 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 and pathFor(id) listing share a strict-by-default loader; only aggregation opts out and skips null records.
  • Daily review history uses reviewDate, while confirmation uses date and 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