api-reference.md

Source-Wire API Reference

Source-Wire exports contract types, schema metadata, validation helpers, and runtime-boundary constants.

It also exports minimal synthetic in-memory runtime boundary helpers and owner-hosted runtime skeleton helpers for proof cases.

It does not export a hosted runtime backend, production API server, production MCP server, database client, connector sync engine, memory engine, or Mission Control UI.

Package Entry Point

Import from the package root:

import {
  SOURCE_WIRE_PACKAGE_VERSION,
  SOURCE_WIRE_MINIMAL_RUNTIME_BOUNDARY,
  SOURCE_WIRE_KNOWLEDGE_PROVIDER_CONTRACT_VERSION,
  SOURCE_WIRE_MEMORY_STORE_CONTRACT_VERSION,
  SOURCE_WIRE_OWNER_HOSTED_SETUP_CONTRACT,
  SOURCE_WIRE_OWNER_HOSTED_RUNTIME_BOUNDARY,
  SOURCE_WIRE_POSTGRES_MEMORY_STORE_PROFILE,
  SOURCE_WIRE_RUNTIME_PROOF_INTAKE_CONTRACT,
  SOURCE_WIRE_RUNTIME_READINESS_CONTRACT,
  SOURCE_WIRE_RUNTIME_SKELETON_BOUNDARY,
  SOURCE_WIRE_RUNTIME_BOUNDARY,
  SOURCE_WIRE_SCHEMA_EXPORTS,
  SOURCE_WIRE_SYNTHETIC_DOCUMENT_INDEX_PROFILE,
  SOURCE_WIRE_VALIDATION_SCHEMA_NAMES,
  callRuntimeSkeletonApiPolicy,
  callRuntimeSkeletonMcpAdapter,
  evaluateOwnerHostedRuntimeFixtureMatrix,
  evaluateKnowledgeProviderConformanceFixtureMatrix,
  evaluateMemoryStoreConformanceFixtureMatrix,
  getOwnerHostedMcpServerRuntimeToolDeclarations,
  handleOwnerHostedApiServerRuntimeRequest,
  handleOwnerHostedMcpServerRuntimeRequest,
  isSourceWireValidationSchemaName,
  runRuntimeSkeletonFixtureMatrix,
  runMinimalRuntimeProofCases,
  summarizeOwnerHostedSetupContract,
  summarizeRuntimeProofIntakeManifest,
  summarizeRuntimeReadinessContract,
  validateSourceWireFile
} from "@source-wire/contracts";

import type {
  SourceWireMinimalRuntimeProofResult,
  SourceWireKnowledgeEvidenceV1,
  SourceWireKnowledgeProviderV1,
  SourceWireMemoryStoreV1,
  SourceWireReadAuditReceiptV1,
  SourceWireSafeErrorV1,
  SourceWireOwnerHostedRuntimeResponse,
  SourceWireOwnerHostedSetupContract,
  SourceWireRuntimeProofIntakeManifest,
  SourceWireRuntimeReadinessContract,
  SourceWireRuntimeSkeletonApiRequest,
  SourceWireRuntimeSkeletonMcpRequest,
  SourceWireRuntimeSkeletonResponse,
  SourceWireRuntimeBoundary,
  SourceWireSourceGraph,
  SourceWireSecondBrainResponse,
  SourceWireValidationResult
} from "@source-wire/contracts";

During local development, use Node.js 22 with npm from the repository root. For the complete local setup path, read the Quickstart.

Install dependencies first:

npm install

Then build:

npm run build

Small import examples live in TypeScript Examples.

Those examples use the package import shape while local typechecking maps @source-wire/contracts to src/index.ts.

Runtime Boundary Exports

Export	Kind	Purpose
SOURCE_WIRE_PACKAGE_VERSION	value	Package version string. The current npm release is 0.2.0.
SourceWireRuntimeBoundary	type	Compile-time shape for the runtime boundary object.
SOURCE_WIRE_RUNTIME_BOUNDARY	value	Declares this package is a contract skeleton, not runtime software.
SOURCE_WIRE_MINIMAL_RUNTIME_BOUNDARY	value	Declares the minimal synthetic in-memory runtime proof boundary.
runMinimalRuntimeProofCase	function	Runs one synthetic owner-hosted API plus MCP proof case through the in-memory policy boundary.
runMinimalRuntimeProofCases	function	Runs multiple synthetic proof cases through the in-memory policy boundary.
SourceWireMinimalRuntimeProofResult	type	Result shape returned by minimal runtime proof helpers.

Example:

import { SOURCE_WIRE_RUNTIME_BOUNDARY } from "@source-wire/contracts";

if (SOURCE_WIRE_RUNTIME_BOUNDARY.runtimeIncluded === false) {
  console.log("Source-Wire has no hosted runtime backend.");
}

Current runtime boundary values:

{
  packageKind: "contract_skeleton",
  runtimeIncluded: false,
  databaseIncluded: false,
  memoryEngineIncluded: false,
  missionControlIncluded: false
}

Minimal synthetic runtime boundary values:

{
  hosting: "owner_hosted",
  implementationMode: "synthetic_in_memory",
  sourceWireHostsUserMemory: false,
  apiServerIncluded: false,
  mcpServerIncluded: false,
  databaseIncluded: false,
  noAutoPromotionByDefault: true
}

Example:

import {
  SOURCE_WIRE_MINIMAL_RUNTIME_BOUNDARY,
  runMinimalRuntimeProofCases
} from "@source-wire/contracts";

console.log(SOURCE_WIRE_MINIMAL_RUNTIME_BOUNDARY.implementationMode);
console.log(runMinimalRuntimeProofCases([]));

For a fuller consumer-style example, read minimal-runtime.ts.

Runtime Skeleton Exports

Export	Kind	Purpose
SOURCE_WIRE_RUNTIME_SKELETON_BOUNDARY	value	Declares the synthetic owner-hosted API policy route and MCP adapter skeleton boundary.
callRuntimeSkeletonApiPolicy	function	Runs one synthetic API-policy request through namespace, capability, and trusted-memory promotion checks.
callRuntimeSkeletonMcpAdapter	function	Maps one synthetic MCP request into the API policy route so MCP cannot bypass Source-Wire policy.
runRuntimeSkeletonFixtureCase	function	Runs one fixture case through the API or MCP skeleton path.
runRuntimeSkeletonFixtureMatrix	function	Runs the synthetic fixture matrix and returns pass/fail case results.
SourceWireRuntimeSkeletonApiRequest	type	Compile-time request shape for the synthetic API policy route.
SourceWireRuntimeSkeletonMcpRequest	type	Compile-time request shape for the synthetic MCP adapter route.
SourceWireRuntimeSkeletonResponse	type	Compile-time response shape for allowed, denied, and review-required cases.

Example:

import {
  SOURCE_WIRE_RUNTIME_SKELETON_BOUNDARY,
  callRuntimeSkeletonMcpAdapter
} from "@source-wire/contracts";

console.log(SOURCE_WIRE_RUNTIME_SKELETON_BOUNDARY.mcpBypassesApiPolicy);

const result = callRuntimeSkeletonMcpAdapter({
  caller: {
    id: "synthetic-agent",
    kind: "mcp_agent",
    namespace: "demo-owner",
    capabilities: ["search_sources"],
    canApproveTrustedMemory: false
  },
  toolName: "source_wire.search_sources",
  ownerNamespace: "demo-owner",
  sourcePacketId: "synthetic-packet",
  requestId: "synthetic-request",
  query: "What source evidence exists?"
});

console.log(result.status);

Related docs:

• Runtime Skeleton Implementation Proof
• Runtime Skeleton Smoke
• Runtime skeleton fixture

Owner-Hosted Runtime Skeleton Exports

Export	Kind	Purpose
SOURCE_WIRE_OWNER_HOSTED_RUNTIME_BOUNDARY	value	Declares the approved synthetic owner-hosted API and MCP runtime skeleton boundary.
handleOwnerHostedApiServerRuntimeRequest	function	Routes one in-process API skeleton request through the Source-Wire API policy contract.
handleOwnerHostedMcpServerRuntimeRequest	function	Routes one in-process MCP skeleton request through the MCP adapter and API policy contract.
evaluateOwnerHostedRuntimeFixtureCase	function	Runs one owner-hosted runtime fixture case through the API or MCP skeleton path.
evaluateOwnerHostedRuntimeFixtureMatrix	function	Runs the full owner-hosted runtime fixture matrix.
getOwnerHostedMcpServerRuntimeToolDeclarations	function	Returns exposed MCP tool declarations while excluding direct database and direct runtime-adapter tools.
SourceWireOwnerHostedRuntimeResponse	type	Compile-time response shape for the owner-hosted runtime skeleton.

Example:

import {
  SOURCE_WIRE_OWNER_HOSTED_RUNTIME_BOUNDARY,
  getOwnerHostedMcpServerRuntimeToolDeclarations
} from "@source-wire/contracts";

console.log(SOURCE_WIRE_OWNER_HOSTED_RUNTIME_BOUNDARY.productionRuntimeIncluded);
console.log(getOwnerHostedMcpServerRuntimeToolDeclarations().map((tool) => tool.toolName));

Related docs:

• Owner-Hosted Runtime Implementation Proof
• Owner-Hosted Runtime Smoke
• Owner-hosted runtime fixture

Schema Registry Exports

Export	Kind	Purpose
SourceWireSchemaName	type	Internal schema registry names: projectContextPack, secondBrainV1, chatExportMessage.
SourceWireSchemaExport	type	Metadata shape for one exported schema.
SOURCE_WIRE_SCHEMA_EXPORTS	value	Object keyed by schema registry name.
SOURCE_WIRE_SCHEMA_EXPORT_LIST	value	Ordered list of schema export metadata.

Example:

import { SOURCE_WIRE_SCHEMA_EXPORT_LIST } from "@source-wire/contracts";

for (const schemaExport of SOURCE_WIRE_SCHEMA_EXPORT_LIST) {
  console.log(schemaExport.packageSubpath);
}

Related docs:

• Schema Exports
• Validation CLI

Owner-Hosted Setup Exports

Export	Kind	Purpose
SOURCE_WIRE_OWNER_HOSTED_SETUP_CONTRACT	value	Owner-brings setup contract for future BYO owner-hosted usage.
SOURCE_WIRE_OWNER_HOSTED_SETUP_REQUIREMENTS	value	Required owner inputs: device/server, PostgreSQL-compatible database, secrets, sources, MCP harness, and review time.
SOURCE_WIRE_OWNER_HOSTED_SETUP_BOUNDARY	value	Explicit false flags for hosted memory, runtime, database migrations, Mission Control, deployment, real data, auto-promotion, and copied AGPL/private code.
SOURCE_WIRE_OWNER_HOSTED_SETUP_STOP_CONDITIONS	value	Conditions that stop setup work before unsafe or out-of-scope behavior.
summarizeOwnerHostedSetupContract	function	Returns counts and public-safety flags for the setup contract.
SourceWireOwnerHostedSetupContract	type	Compile-time setup contract shape.
SourceWireOwnerHostedSetupRequirement	type	Compile-time owner-brings checklist item shape.
SourceWireOwnerHostedSetupBoundary	type	Compile-time setup boundary shape.
SourceWireOwnerHostedSetupStopCondition	type	Compile-time setup stop condition shape.

Example:

import {
  SOURCE_WIRE_OWNER_HOSTED_SETUP_CONTRACT,
  summarizeOwnerHostedSetupContract
} from "@source-wire/contracts";

const summary = summarizeOwnerHostedSetupContract(SOURCE_WIRE_OWNER_HOSTED_SETUP_CONTRACT);

console.log(summary.sourceWireHostsMemoryByDefault);

Related docs:

• Owner-Hosted Setup Contract
• Owner-hosted setup fixture

Runtime Readiness Exports

Export	Kind	Purpose
SOURCE_WIRE_RUNTIME_READINESS_CONTRACT	value	Synthetic contract for runtime-readiness gates before public owner-hosted runtime implementation.
SOURCE_WIRE_RUNTIME_READINESS_BOUNDARY	value	Explicit false flags for runtime implementation, API runtime, MCP runtime, database migrations, deployment, real data, copied code, auto-promotion, and package version changes.
SOURCE_WIRE_RUNTIME_READINESS_REQUIRED_CASES	value	Required runtime-readiness fixture case IDs.
summarizeRuntimeReadinessContract	function	Returns counts and public-safety flags for the runtime-readiness contract.
SourceWireRuntimeReadinessContract	type	Compile-time runtime-readiness contract shape.
SourceWireRuntimeReadinessCase	type	Compile-time runtime-readiness fixture case shape.
SourceWireRuntimeReadinessBoundary	type	Compile-time runtime-readiness boundary shape.

Example:

import {
  SOURCE_WIRE_RUNTIME_READINESS_CONTRACT,
  summarizeRuntimeReadinessContract
} from "@source-wire/contracts";

const summary = summarizeRuntimeReadinessContract(SOURCE_WIRE_RUNTIME_READINESS_CONTRACT);

console.log(summary.runtimeImplementationIncluded);

Related docs:

• Runtime Readiness Contract
• Runtime readiness fixture

Runtime Proof Intake Exports

Export	Kind	Purpose
SOURCE_WIRE_RUNTIME_PROOF_INTAKE_CONTRACT	value	Synthetic contract for redacted private-proof metadata intake before public runtime PRD refresh.
SOURCE_WIRE_RUNTIME_PROOF_INTAKE_BOUNDARY	value	Explicit false flags for private paths, raw private content, real data, secrets, copied code, runtime implementation, migrations, and deployment.
SOURCE_WIRE_RUNTIME_PROOF_INTAKE_REQUIRED_CASES	value	Required runtime-readiness case IDs covered by proof-intake metadata.
summarizeRuntimeProofIntakeManifest	function	Returns counts and public-safety flags for a runtime proof intake manifest.
SourceWireRuntimeProofIntakeManifest	type	Compile-time proof-intake manifest shape.
SourceWireRuntimeProofIntakeProof	type	Compile-time proof metadata entry shape.
SourceWireRuntimeProofIntakeBoundary	type	Compile-time proof-intake boundary shape.

Example:

import {
  SOURCE_WIRE_RUNTIME_PROOF_INTAKE_CONTRACT,
  summarizeRuntimeProofIntakeManifest
} from "@source-wire/contracts";

console.log(SOURCE_WIRE_RUNTIME_PROOF_INTAKE_CONTRACT.status);

const summary = summarizeRuntimeProofIntakeManifest({
  fixtureType: "source-wire-runtime-proof-intake-manifest",
  fixtureSafety: "synthetic",
  contractVersion: "source-wire-runtime-proof-intake.v1",
  boundary: SOURCE_WIRE_RUNTIME_PROOF_INTAKE_CONTRACT.boundary,
  proofs: [],
  decision: {
    privateProofBaselineAccepted: false,
    runtimePrdRefreshAllowed: false,
    runtimeImplementationAllowed: false,
    allowedNextAction: "Provide redacted private-proof metadata first."
  }
});

console.log(summary.runtimeImplementationAllowed);

Related docs:

• Runtime Proof Intake Contract
• Runtime proof intake fixture

Validation Helper Exports

Export	Kind	Purpose
SourceWireValidationSchemaName	type	CLI validation schema names: project-context-pack, second-brain-v1, chat-export-message.
SourceWireValidationResult	type	Result shape returned by validateSourceWireFile.
SOURCE_WIRE_VALIDATION_SCHEMA_NAMES	value	Supported validation schema names.
isSourceWireValidationSchemaName	function	Type guard for validation schema names.
validateSourceWireFile	function	Validates an explicit local file against a supported schema name.

Example:

import {
  isSourceWireValidationSchemaName,
  validateSourceWireFile
} from "@source-wire/contracts";

const schemaName = "project-context-pack";

if (isSourceWireValidationSchemaName(schemaName)) {
  const result = await validateSourceWireFile(
    schemaName,
    "examples/fixtures/project-context-pack/project-context.json"
  );

  console.log(result.ok);
}

The validation helper validates explicit files only.

It does not crawl directories, import sources, sync connectors, call servers, call databases, call memory engines, create trusted Memory Records, or promote candidate memories.

KnowledgeProvider And MemoryStore Exports

These exports define two sibling ports behind Source-Wire API policy.

Export	Kind	Purpose
SOURCE_WIRE_KNOWLEDGE_PROVIDER_CONTRACT_VERSION	value	Exact knowledge-provider.v1 contract version.
SOURCE_WIRE_SYNTHETIC_DOCUMENT_INDEX_PROFILE	value	Read-only synthetic document-index profile.
SOURCE_WIRE_SYNTHETIC_RELATIONAL_VIEW_PROFILE	value	Read-only synthetic relational-view profile.
evaluateKnowledgeProviderConformanceFixtureMatrix	function	Evaluates both provider profiles through one synthetic ruleset.
SourceWireKnowledgeProviderV1	type	Optional read-only provider port.
SourceWireKnowledgeEvidenceV1	type	Scoped, cited, versioned evidence envelope.
SourceWireSafeErrorV1	type	Constant-shape, redacted error envelope with bounded retry metadata.
SOURCE_WIRE_MEMORY_STORE_CONTRACT_VERSION	value	Exact memory-store.v1 contract version.
SOURCE_WIRE_POSTGRES_MEMORY_STORE_PROFILE	value	PostgreSQL-only profile with adopter infrastructure ownership and Source-Wire logical schema ownership.
SOURCE_WIRE_SYNTHETIC_POSTGRES_MEMORY_STORE_POSTURE	value	Synthetic schema, role, query-safety, and boundary posture.
evaluateMemoryStoreConformanceFixtureMatrix	function	Evaluates memory lifecycle, audit, compatibility, and posture cases.
validateSourceWireReadAuditReceiptV1	function	Validates exact, single-use protected-read receipt binding.
SourceWireMemoryStoreV1	type	PostgreSQL-only v1 memory port.
SourceWireReadAuditReceiptV1	type	Durable protected-read audit receipt shape.

Safe contract inspection does not create a connection:

import {
  SOURCE_WIRE_POSTGRES_MEMORY_STORE_PROFILE,
  SOURCE_WIRE_SYNTHETIC_DOCUMENT_INDEX_PROFILE
} from "@source-wire/contracts";

console.log(SOURCE_WIRE_POSTGRES_MEMORY_STORE_PROFILE.backend);
console.log(SOURCE_WIRE_POSTGRES_MEMORY_STORE_PROFILE.sourceWireHostsUserMemory);
console.log(SOURCE_WIRE_SYNTHETIC_DOCUMENT_INDEX_PROFILE.accessMode);

This prints postgresql, false, and read_only. It does not connect to PostgreSQL or an external provider. A memory-only installation is valid, and an external knowledge base is optional through the read-only provider contract.

Related docs:

• Knowledge Provider And Memory Store Boundary
• KnowledgeProvider v1 Contract
• MemoryStore v1 Contract

Contract Type Groups

These exports are TypeScript types only.

They describe contract shapes. They do not run behavior.

Source Graph Types

Export	Purpose
SourceWireSourceClass	Source class identifiers such as Markdown vault, chat export, project context pack, second-brain example, or custom.
SourceWireSensitivity	Source sensitivity labels: public, internal, private, unknown.
SourceWireFreshness	Source freshness labels: fresh, changed, stale, unknown.
SourceWireCitation	Citation pointer for a source segment.
SourceWireSourceCollection	Source collection metadata.
SourceWireSourceItem	Source item metadata.
SourceWireSourceSegment	Addressable source segment with content and citation.
SourceWireSourceEdgeKind	Source graph edge kind.
SourceWireSourceEdge	Relationship between source graph objects.
SourceWireSourceGraph	Full source graph payload.

Related doc:

• Source Graph Adapter Contract

Source Connection Types

Export	Purpose
SourceWireSyncMode	Sync mode: manual, scheduled, or external trigger.
SourceWireSyncStatus	Sync status: never synced, synced, partial, or failed.
SourceWireCandidatePolicy	Candidate policy: disabled or prepare for review.
SourceWireSourceConnection	Source connection configuration shape.
SourceWireSourceSyncResult	Source sync result counters and no-auto-promotion marker.

Related doc:

• Source Connection Contract

Second-Brain Types

Export	Purpose
SourceWireSecondBrainIntent	High-level intent classification.
SourceWireSearchRadius	Search radius: project, source, or global.
SourceWireSecondBrainRequest	Request shape for /2nd-brain.
SourceWireEvidenceGap	Missing or weak evidence marker.
SourceWireSecondBrainResponse	Source-backed response shape.

Related doc:

• second-brain.v1 Contract

MCP Tool Behavior Types

Export	Purpose
SourceWireMcpToolGroup	Tool group labels for memory search, source search, maintenance, second-brain, context assembly, and handoff.
SourceWireMcpToolBehavior	Public MCP behavior contract shape.

Related doc:

• MCP Tool Behavior Contract

Owner-Hosted Setup Types

Export	Purpose
SourceWireOwnerHostedSetupStatus	Current setup contract status.
SourceWireOwnerHostedSetupRequirementKind	Required owner input identifiers.
SourceWireOwnerHostedSetupRequirement	Owner-brings checklist item.
SourceWireOwnerHostedSetupBoundary	Explicit setup non-goals and false runtime flags.
SourceWireOwnerHostedSetupStopCondition	Unsafe or out-of-scope setup stop condition.
SourceWireOwnerHostedSetupContract	Full owner-hosted setup contract payload.
SourceWireOwnerHostedSetupReadinessSummary	Summary returned by summarizeOwnerHostedSetupContract.

Related doc:

• Owner-Hosted Setup Contract

Fixture Types

Export	Purpose
SourceWireFixtureSafety	Fixture safety label.
SourceWireFixtureMetadata	Shared fixture metadata.
SourceWireProjectContextPack	Synthetic Project Context Pack fixture shape.
SourceWireSecondBrainFixture	Synthetic second-brain request and response fixture shape.
SourceWireChatExportMessage	Synthetic chat export message shape.
SourceWireOwnerHostedApiMcpBoundaryFixture	Synthetic owner-hosted API plus MCP boundary proof-case fixture shape.
SourceWireOwnerHostedApiMcpProofCase	Synthetic proof case for owner-hosted API plus MCP policy behavior.

Related docs:

• Fixtures README
• TypeScript Examples
• Quickstart

What Is Not Exported

Source-Wire does not currently export:

• API server runtime,
• MCP server runtime,
• database client,
• migrations,
• PostgreSQL or pgvector setup,
• memory-engine integration,
• connector sync engine,
• Mission Control UI,
• trusted Memory Record promotion behavior,
• private implementation code.

Release Boundary

Current package posture:

• license is Apache-2.0,
• current package version is 0.2.0,
• LICENSE file exists,
• npm package @source-wire/contracts@0.2.0 is published,
• GitHub release v0.2.0 is published,
• runtime backend work is blocked.

This API reference documents the current contract package surface only.