Factory docs, home
Page navigation

Pre-release documentation. Proposed designs are labelled in the page; acceptance evidence is maintained in the build review. Local paths appear as placeholders. Current state: Build review.

The private draft entry software-factory/temporal-planning evaluates caller-owned source snapshots, date claims and constraints. Install the reviewed tarball, then use its public JavaScript or TypeScript contract. It needs Node 26.8.1 or later, with canonical time-zone support. There are no npm runtime dependencies, Node declaration requirements, storage, Git, Portfolio, provider or credential setup. Import and evaluation start no work outside the calculation.

This implements only T36.1 of the original E36 design. Separate source and installed-package review passed; current integration evidence records coordinator checks. It was accepted locally on 1 October 2026 (owner-designated acceptance reviewer, after independent Opus 5.5 and Fable 5.1 reviews); broader host qualification and E36 acceptance remain open. There is no capacity forecast, material ranking, Commitment, journal workflow or delivery/dispatch facility.

Evaluate a civil quarter

Save this as dates.mjs and run node dates.mjs in your installed application. This is synthetic attributed evidence: replace it with the source snapshots your application owns. The output retains the whole quarter, not a UTC release appointment.

import { evaluateTemporalPlan, parseTemporalPlan } from 'software-factory/temporal-planning';

const scope = { namespace: 'example', productId: 'reader' };
const asOf = '2026-09-30T08:00:00.000Z'; // Sample the caller's clock once.
const source = { id: 'platform', revision: 1, contentDigest: `sha256:${'a'.repeat(64)}` };
const inputs = {
  protocol: 'sf-temporal-inputs/1', scope, coverage: 'complete',
  subjects: [{ id: 'release', label: 'Platform release statement' }],
  sources: [{ protocol: 'sf-temporal-source/1', scope, ...source,
    locator: 'urn:example:announcement', publishedAt: null,
    observedAt: asOf, checkedAt: asOf, validUntil: '2026-10-07T08:00:00.000Z',
    validation: { state: 'validated' } }],
  claims: [{ protocol: 'sf-date-claim/1', scope, id: 'release-quarter', revision: 1,
    subjectId: 'release', kind: 'announced', source,
    basis: { kind: 'quoted', text: 'Expected during Q4 2026.' },
    date: { domain: 'civil', precision: 'quarter', zone: 'Europe/London', year: 2026, quarter: 4 },
    confidence: { state: 'not-stated' }, expiresAt: null, lifecycle: { state: 'active' } }],
  constraints: [],
};
const policy = { protocol: 'sf-temporal-policy/1', scope, id: 'fresh-sources',
  revision: 1, maxSourceAgeMs: 604800000 };
const plan = evaluateTemporalPlan(inputs, policy, asOf);
const reopened = parseTemporalPlan(JSON.parse(JSON.stringify(plan)));
console.log(JSON.stringify({ summary: reopened.summary, support: reopened.subjectDates[0].claims[0].support }));

Inputs and interpretation

The entry exports parseDateClaim, parseTemporalConstraint, parseTemporalPolicy, evaluateTemporalPlan, parseTemporalPlan, TemporalPlanningError, TEMPORAL_LIMITS, TEMPORAL_CIVIL_POLICY and their public data types. The installed declarations define every exact discriminated shape. Parsers copy and deeply freeze results without freezing the caller's objects. Every evaluation revalidates its inputs.

All source snapshots, claims, constraints and policy bind the same {namespace, productId}. IDs are 1–63 lowercase ASCII letters/digits/hyphens beginning alphanumeric; revisions are 1–1,000,000. A source reference must match a supplied source ID, revision and sha256: digest exactly. Scope mismatches, missing references and duplicate identities refuse the entire evaluation. Source validation is the caller's declaration: the evaluator neither authenticates it nor issues Evidence or a Verdict. Quoted/derived basis and stated confidence remain attribution, never generated probability.

Civil dates retain day/month/calendar-quarter/range precision and their canonical IANA zone. Ranges are inclusive. Instant values/ranges are explicit millisecond UTC timestamps. Years are 1970–9999. Civil comparisons require the same zone; different zones or civil/instant mixtures are unknown. Unsupported or aliased zones refuse. V1 resolves no local wall time, DST gap/fold, fiscal quarter or relative date. An observed event is usable only when its entire instant support is at or before asOf; future/straddling observed instants and civil observed dates remain unusable unknowns. Future announced/expected dates are ordinary claims and never become observed merely because time passes.

Source publication, observation and check times must be ordered and no later than asOf. At equality with source expiry, claim expiry or the policy's source-age limit, evidence is unusable. A derived claim needs every named basis source current and validated. Withdrawn/superseded claims remain inspectable but unusable. Supersession requires a different supplied claim from the same primary source, subject and kind, with its exact revision; cycles refuse. Current snapshots contain one revision per stable claim ID. The host owns monotonic revision/history across snapshots until a future durable facade exists.

Constraints name a target subject and claim kind and carry an owner, hard/advisory severity and purpose. after also names a predecessor plus nonnegative civil-day/millisecond lead; within/outside supply a known window. Every dependency edge orders subjects, even when claim kinds differ. Self-edges and cycles, including advisory or mixed-kind cycles, refuse. Distinct stages need distinct subjects. Topological order is not selected priority or a delivery schedule.

All usable source alternatives participate. Disjoint same-kind claims remain a source disagreement; overlaps are never intersected into an artificially precise date. A constraint is satisfied only when all relevant alternatives guarantee it, violated only when all rule it out, and otherwise unknown. For predecessor support [p0,p1], target [t0,t1] and lag L, after satisfies at t0 >= p1 + L, violates at t1 < p0 + L, and is otherwise unknown. No source is preferred by recency or confidence. Unknown/expired alternatives remain visible in the overall unknowns.

Results, failures and history

An immutable sf-temporal-plan/1 contains full canonical inputs/policy, their digests, dependency order, source/constraint assessments, conflicts/advisories/unknowns and its digest. Summary is has-conflicts, has-unknowns or no-conflict-found; none means ready, authorised or complete. Only hard violations count as conflicts: a plan whose only finding is a violated advisory constraint still reports no-conflict-found, so read advisories as well. usableClaims uses exact/partial/unknown Count semantics; incomplete coverage never produces an exact zero.

TemporalPlanningError.code is INVALID, LIMIT or CORRUPT. Its reason distinguishes shape/version/identity/scope/reference/duplicate/date/zone/future-metadata/cycle/size/bounds/digest/derived-result. Invalid dates produce a coded refusal, not a native date exception. Contradictory but structurally valid claims and uncertain constraint comparisons are inspectable results. Accessors and non-JSON input refuse; arbitrary Proxy/caller-code sandboxing is not promised.

Bounds: 64 subjects, 128 source snapshots, 256 claims, 16 claims per subject/kind, 128 constraints, 4 derived-basis sources, 280-character labels/reasons/confidence and 2,000-character basis/locator text. Canonical input and output are each bounded to 1,048,576 UTF-8 bytes and depth 64. Source freshness is 1–31,536,000,000 ms; leads at most 366,000 civil days or their millisecond equivalent. Overflow/excess refuses rather than truncating.

Store the JSON artefact yourself. parseTemporalPlan verifies digests and the fixed v1 semantic result using its recorded inputs, policy and asOf; it reads no current clock and does not require today's zone catalogue. New snapshots/policies produce new immutable artefacts. Historic validity is not current evidence or permission. No migration or writes to any existing module record occur.

The draft external-consumer proof uses an installed tarball, substitute caller sources/clocks, source/package parity, read-only permissions, historical reopening without zone lookups and wrong-source/cross-scope/cycle refusals. Other platforms and future E36 workflows require their own evidence.

Source: docs/how-to/adopt-temporal-planning.md