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.

In progress: source candidate for an optional pure projection. Independent source, installed-package, combined integration and CI/Fable checks remain separate gates. This module adds no provider contact or retry.

Import software-factory/provider-diagnostics. Give diagnoseProviderObservation only selected facts from an actual retained public Producer result and its receipt. The following caller extraction uses the existing public Producers and Command journal canonical JSON helper; the projection itself imports neither module.

import {diagnoseProviderObservation} from 'software-factory/provider-diagnostics';
import {sha256Tagged} from 'software-factory/producer';
import {canonicalJson} from 'software-factory/command-journal';

export function providerDiagnostic(result) {
  const receipt = result.receipt;
  const transport = receipt.transport;
  const outcome = result.status === 'proposal'
    ? {status: 'proposal'} : {status: result.status, reason: result.reason};
  return diagnoseProviderObservation({
    protocol: 'sf-provider-diagnostic-input/1',
    source: {
      protocol: receipt.protocol, dispatchId: receipt.dispatchId,
      requestDigest: receipt.request.digest,
      receiptDigest: sha256Tagged(canonicalJson(receipt, 'retained receipt')),
      commissionDigest: receipt.commission,
    },
    provider: receipt.provider, outcome,
    contact: receipt.contact, remote: receipt.remote, exchange: receipt.exchange,
    observation: transport.kind === 'openai-responses'
      ? {kind: transport.kind, httpStatus: transport.response.status,
          credentialEchoed: transport.response.credentialEchoed,
          truncatedDiagnostic: transport.response.truncatedDiagnostic}
      : {kind: transport.kind},
  });
}

Keep the original result, reason, receipt and consumption independently. A receipt-only record supplies outcome: null; it cannot recover a missing result. A digest attributes the caller's exact supplied bytes, not their authenticity. Resolving policy requires the caller's matching original commission and native digest; this projection never substitutes the current policy.

An OpenAI 429 or 5xx is an observed HTTP status. It proves neither a body cause nor retry permission. Credential echo suppresses attribution; native authentication keeps its original outcome. Interrupted work remains interrupted and remote uncertainty remains unknown. Claude's retained public receipt does not expose the CLI error subtype or API status, so those details remain unavailable. A warning followed by a successful proposal does not become a failure. Messages, stderr, body error tokens and prompts are never inputs.

Both input and complete output are bounded to 4,096 canonical UTF-8 bytes, depth eight and 128 own descriptor slots. Inputs use exact fields and native ID/reason grammars. Excess data refuses; nothing truncates. Results are immutable. Unsupported positive protocol versions, malformed input, contradictory facts and overflow have fixed distinct refusals. Native Promise data is observed only within the same bounded traversal, never awaited or accepted; accessors and generic thenables are not evaluated. Arbitrary hostile object execution is not a sandbox guarantee.

Honest limits: caller-supplied facts are not authenticated Evidence; there is no storage, model, provider client, policy decision, backfill, migration or current-validity claim. Existing provider APIs and historical bytes are unchanged. No live provider qualification or publication is established by these offline checks.

Source: docs/how-to/adopt-provider-diagnostics.md