This E29 draft offers software-factory/portfolio for caller-owned registration, observation imports and sourced views. Independent review passed; it was merged on 1 October 2026 after an Opus 5.5 review and accepted locally the same day by the owner-designated acceptance reviewer after a Fable 5.1 review. It grants no delivery authority and starts no Factory, Dashboard, background collector or live onboarding.
Install the reviewed private tarball as described in Journal adoption. Portfolio has no runtime package dependency. Its runtime closure is portfolio, portfolio-inventory, journal, canonical-json and errors; the declaration closure also includes the neutral reporting-contract. The public declarations require no caller Node development types. The current proof is Node 26.8.1 on macOS arm64 with /usr/bin/git; the package engine range does not qualify other hosts.
Register an existing primary checkout
Portfolio legitimately requires a real primary Git checkout for registration. Supply its canonical absolute path and a trusted Git executable through PortfolioOptions.git. The default is /usr/bin/git; on macOS it is Apple's developer-tool shim. Registration and explicit inspectProduct use bounded metadata commands with isolated Git configuration and no permitted transport. The caller owns the journal, checkout, configuration and lifecycle.
Save this as portfolio.mjs and run node portfolio.mjs /absolute/primary/checkout in a directory where a new caller-portfolio.sqlite may be created:
import { realpathSync } from 'node:fs';
import { CommandJournal } from 'software-factory/command-journal';
import { Portfolio } from 'software-factory/portfolio';
if (!process.argv[2]) throw new Error('Supply an existing primary Git checkout');
const journal = CommandJournal.open('caller-portfolio.sqlite');
try {
const portfolio = new Portfolio(journal, { git: { gitPath: '/usr/bin/git' } });
await portfolio.registerProduct({
commandId: 'register-caller', expectedVersion: 0,
productId: 'caller', displayName: 'Caller', root: realpathSync(process.argv[2]),
});
console.log(portfolio.productView('caller', {
window: { start: '2026-09-01T00:00:00.000Z', end: '2026-09-28T00:00:00.000Z' },
asOf: '2026-09-28T12:00:00.000Z',
}));
} finally {
journal.close();
}
The example keeps its journal for inspection. Registration binds one logical Product to the observed root/common-directory device and inode identity. A linked worktree, alias or replaced identity is refused or reported unavailable; nothing silently rebinds or recreates it. Registration alone records no activity, release, usage or current repository observation, so absent facts remain unknown. Use inspectProduct explicitly to record current repository metadata. Views run no Git, start no commands and work with CommandJournal.openReadOnly even when a checkout is absent.
Import and query sourced facts
recordObservations(productId, observations) accepts bounded facts for that Product. Keep each collector/record ID stable: an identical revision is a duplicate, an older revision is obsolete, a higher revision corrects it and a retraction withdraws it without erasing history. A conflicting batch writes nothing. A source name is attribution, not authentication. Source repository facts are reserved to Portfolio's own inspection.
recordUsage(receipts) accepts the strict usage-receipt/1 shape. Construct a typed receipt with Parameters<Portfolio['recordUsage']>[0][number]; prompts, completions and authentication fields are refused. Usage is deduplicated globally and session attribution cannot move between Products. Unknown counters stay unknown. Usage coverage from recordUsageObservations is deliberately Portfolio-wide: a complete declaration applies to every Product, including Products with no recorded usage. Declare it only when that whole population was observed.
Use productView, portfolioView and currentConditions with an explicit [start, end) window and asOf capture cutoff. Missing, stale, contradictory or partial coverage cannot establish an exact zero. Activity never establishes a release; a historical Verdict and its current validity stay separate. The exact source contract and failure boundaries are in the Portfolio reference.
Retry, history and proof
Keep command IDs and expected versions with registration/rename requests. Exact command retries return recorded results. Registration always checks the root first, so an unavailable root cannot be bypassed by replay. Concurrent identical imports may both receive the original recorded count from one command receipt; those counts are history, not quantities to add. Durable stream events establish what was written once.
The draft consumer uses two disposable real checkouts and a caller journal. It checks registration and unchanged Git metadata, source/package command replay, observations and usage, historical raw rows including receipts/events/outbox, strict public declarations, read-only restart, concurrent import, wrong/replaced/missing identities, corrupt storage and cross-Product refusal. Runtime source, stored protocols and historical receipts are unchanged. It was accepted locally on 1 October 2026; this is local adoption proof only.
