@jungjaehoon/mama-core 2.4.1 → 4.1.0

package/dist/connectors/types.d.ts

@@ -1,117 +0,0 @@
-import type { Buffer } from 'node:buffer';
-import type { MemoryScopeRef } from '../memory/types.js';
-export interface ConnectorEventIndexRecord {
-    event_index_id: string;
-    source_connector: string;
-    source_type: string;
-    source_id: string;
-    source_locator: string | null;
-    channel: string | null;
-    author: string | null;
-    title: string | null;
-    content: string;
-    event_datetime: number | null;
-    event_date: string | null;
-    source_timestamp_ms: number;
-    source_cursor: string | null;
-    tenant_id: string | null;
-    project_id: string | null;
-    memory_scope_kind: string | null;
-    memory_scope_id: string | null;
-    metadata_json: string | null;
-    artifact_locator: string | null;
-    artifact_title: string | null;
-    content_hash: Buffer;
-    operator_ingest_seq: number;
-    operator_observation_seq: number;
-    indexed_at: string;
-    updated_at: string;
-    expires_at: string | null;
-}
-export interface UpsertConnectorEventIndexInput {
-    source_connector: string;
-    source_type: string;
-    source_id: string;
-    /** Stable upstream entity across revisions; enables grant-bounded change-history reads. */
-    source_entity_id?: string | null;
-    source_locator?: string | null;
-    channel?: string | null;
-    author?: string | null;
-    title?: string | null;
-    content: string;
-    event_datetime?: number | null;
-    event_date?: string | null;
-    source_timestamp_ms?: number | null;
-    source_cursor?: string | null;
-    tenant_id?: string | null;
-    project_id?: string | null;
-    memory_scope_kind?: string | null;
-    memory_scope_id?: string | null;
-    metadata_json?: string | null;
-    metadata?: unknown;
-    artifact_locator?: string | null;
-    artifact_title?: string | null;
-    content_hash?: Buffer | Uint8Array | null;
-    indexed_at?: string;
-    updated_at?: string;
-    expires_at?: string | null;
-}
-export interface ConnectorEventIndexCursorRecord {
-    connector_name: string;
-    last_seen_timestamp_ms: number;
-    last_seen_source_id: string;
-    last_sweep_at: string | null;
-    last_success_at: string | null;
-    last_error: string | null;
-    last_error_at: string | null;
-    indexed_count: number;
-}
-export interface UpsertConnectorEventIndexCursorInput {
-    connector_name: string;
-    last_seen_timestamp_ms?: number;
-    last_seen_source_id?: string;
-    last_sweep_at?: string | null;
-    last_success_at?: string | null;
-    last_error?: string | null;
-    last_error_at?: string | null;
-    indexed_count?: number;
-}
-export interface ConnectorEventSearchHit extends ConnectorEventIndexRecord {
-    rank: number;
-    score: number;
-}
-export interface RawSearchScopeFilter {
-    kind: MemoryScopeRef['kind'];
-    id: string;
-}
-export interface RawSearchInput {
-    query: string;
-    connectors?: string[];
-    scopes?: RawSearchScopeFilter[];
-    fromMs?: number;
-    toMs?: number;
-    cursor?: string;
-    limit?: number;
-}
-export interface RawSearchHit {
-    raw_id: string;
-    connector: string;
-    source_id: string;
-    channel_id: string | null;
-    author_label: string | null;
-    created_at: string | null;
-    content_preview: string;
-    score: number;
-    source_ref: string | null;
-    metadata: Record<string, unknown>;
-}
-/** Explicit detail access includes the complete source; search results remain bounded previews. */
-export interface RawDocument extends RawSearchHit {
-    content: string;
-}
-export interface RawSearchResult {
-    hits: RawSearchHit[];
-    next_cursor: string | null;
-}
-export type ConnectorEventStalenessStatus = 'healthy' | 'stale-but-warming' | 'warn' | 'unhealthy' | 'never_swept';
-//# sourceMappingURL=types.d.ts.map

package/dist/connectors/types.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/context-compile/boundary-defaults.d.ts

@@ -1,12 +0,0 @@
-import type { ContextBoundary, ContextProjectRef, ContextRange } from './types.js';
-import type { MemoryScopeRef } from '../memory/types.js';
-export type ContextBoundaryReadableInput = {
-    scopes?: MemoryScopeRef[];
-    connectors?: string[];
-    project_refs?: ContextProjectRef[];
-    tenant_id?: string | null;
-    range?: ContextRange;
-    as_of?: string | number | null;
-};
-export declare function applyContextBoundaryReadDefaults<T extends ContextBoundaryReadableInput>(input: T, boundary: ContextBoundary | undefined): T;
-//# sourceMappingURL=boundary-defaults.d.ts.map

package/dist/context-compile/boundary-defaults.js

@@ -1,105 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.applyContextBoundaryReadDefaults = applyContextBoundaryReadDefaults;
-function parseBoundaryTimeMs(value, field) {
-    if (value === null || value === undefined) {
-        return null;
-    }
-    if (typeof value === 'number' && Number.isFinite(value)) {
-        return Math.floor(value);
-    }
-    if (typeof value === 'string') {
-        const trimmed = value.trim();
-        if (trimmed.length === 0) {
-            throw new Error(`Invalid context boundary ${field}: ${String(value)}`);
-        }
-        const numeric = Number(trimmed);
-        if (Number.isFinite(numeric)) {
-            return Math.floor(numeric);
-        }
-        const parsed = Date.parse(trimmed);
-        if (Number.isFinite(parsed)) {
-            return parsed;
-        }
-    }
-    throw new Error(`Invalid context boundary ${field}: ${String(value)}`);
-}
-function rangeBoundaryMs(value, field) {
-    if (value === undefined) {
-        return null;
-    }
-    if (typeof value === 'number' && Number.isFinite(value)) {
-        return Math.floor(value);
-    }
-    throw new Error(`Invalid context boundary ${field}: ${String(value)}`);
-}
-function intersectRange(range, boundaryRange) {
-    if (!boundaryRange) {
-        return range;
-    }
-    const requestedStartMs = rangeBoundaryMs(range?.start_ms, 'range.start_ms');
-    const requestedEndMs = rangeBoundaryMs(range?.end_ms, 'range.end_ms');
-    const boundaryStartMs = rangeBoundaryMs(boundaryRange.start_ms, 'boundary.range.start_ms');
-    const boundaryEndMs = rangeBoundaryMs(boundaryRange.end_ms, 'boundary.range.end_ms');
-    const startMs = requestedStartMs === null
-        ? boundaryStartMs
-        : boundaryStartMs === null
-            ? requestedStartMs
-            : Math.max(requestedStartMs, boundaryStartMs);
-    const endMs = requestedEndMs === null
-        ? boundaryEndMs
-        : boundaryEndMs === null
-            ? requestedEndMs
-            : Math.min(requestedEndMs, boundaryEndMs);
-    if (startMs === null && endMs === null) {
-        return undefined;
-    }
-    if (startMs !== null && endMs !== null && startMs > endMs) {
-        throw new RangeError(`Context boundary range is empty after intersection: start_ms ${startMs} > end_ms ${endMs}`);
-    }
-    return {
-        ...(startMs !== null ? { start_ms: startMs } : {}),
-        ...(endMs !== null ? { end_ms: endMs } : {}),
-    };
-}
-function clampAsOf(requested, boundaryAsOf) {
-    const requestedMs = parseBoundaryTimeMs(requested, 'as_of');
-    const boundaryMs = parseBoundaryTimeMs(boundaryAsOf, 'boundary.as_of');
-    if (requestedMs === null) {
-        return boundaryAsOf ?? null;
-    }
-    if (boundaryMs === null) {
-        return requested ?? null;
-    }
-    return requestedMs <= boundaryMs ? (requested ?? null) : (boundaryAsOf ?? null);
-}
-function applyContextBoundaryReadDefaults(input, boundary) {
-    if (!boundary) {
-        return input;
-    }
-    const requestedTenantId = input.tenant_id;
-    const boundaryTenantId = boundary.tenant_id;
-    if (requestedTenantId !== undefined &&
-        requestedTenantId !== null &&
-        boundaryTenantId !== undefined &&
-        boundaryTenantId !== null &&
-        requestedTenantId !== boundaryTenantId) {
-        throw new Error('Requested tenant is outside the context boundary');
-    }
-    const scopedInput = {
-        ...input,
-        scopes: input.scopes === undefined ? boundary.scopes : input.scopes,
-        connectors: input.connectors === undefined ? boundary.connectors : input.connectors,
-        project_refs: input.project_refs === undefined ? boundary.project_refs : input.project_refs,
-        range: intersectRange(input.range, boundary.range),
-        as_of: clampAsOf(input.as_of, boundary.as_of),
-    };
-    if (boundaryTenantId !== undefined || requestedTenantId !== undefined) {
-        return {
-            ...scopedInput,
-            tenant_id: boundaryTenantId !== undefined ? boundaryTenantId : requestedTenantId,
-        };
-    }
-    return scopedInput;
-}
-//# sourceMappingURL=boundary-defaults.js.map

package/dist/context-compile/channel-grant.js

@@ -1,66 +0,0 @@
-"use strict";
-/**
- * The raw visibility rule, in one place.
- *
- * There were three copies of this decision. The reader had one, twin-ref validation had a
- * second, and the standalone citation path had a third that carried a comment promising it
- * reproduced the reader "clause for clause" - which it did, until the reader changed. The
- * differential test that was supposed to catch that kept passing, because its fixtures
- * never exercised the branch production takes. Copies pinned by a test are still copies;
- * the test just tells you later.
- *
- * So the rule lives here, and everything that needs it takes it from here. It has to exist
- * in two compiled forms - a boolean for checking one row you already hold, and SQL for
- * selecting rows you do not - and those two forms are adjacent in this file with a
- * differential over a matrix that includes what production sends. Two forms of one rule is
- * the irreducible minimum; three copies of a decision is not.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isChannelGranted = isChannelGranted;
-exports.channelGrantClause = channelGrantClause;
-/**
- * The rule: an event is visible when its connector is granted and its channel is one of
- * the channels granted for that connector.
- *
- * A connector absent from the grant is denied. A connector present with an empty list is
- * also denied - "granted the connector but no channel of it" is not a useful state, and
- * reading it as "all channels" is how a grant becomes a wildcard.
- */
-function isChannelGranted(connector, channel, grant) {
-    if (typeof channel !== 'string' || channel.length === 0)
-        return false;
-    const channels = grant[connector];
-    return Array.isArray(channels) && channels.includes(channel);
-}
-/**
- * The same rule as a SQL predicate.
- *
- * Returns null when nothing is readable, which callers must treat as "select nothing"
- * rather than "no filter" - an empty WHERE is how a visibility rule turns into a full scan
- * at the exact moment it should have refused.
- *
- * `requestedConnectors` narrows further: a connector the caller did not ask for is not read
- * even though it is granted. The grant is a ceiling, never an instruction.
- */
-function channelGrantClause(grant, requestedConnectors, columns) {
-    const pairs = [];
-    const params = [];
-    for (const [connector, channels] of Object.entries(grant)) {
-        if (Array.isArray(requestedConnectors) && !requestedConnectors.includes(connector))
-            continue;
-        // Array.isArray, not `?? []`: the boolean form denies a malformed grant quietly, so
-        // this one must not throw on it. Two forms of a rule that disagree on bad input have
-        // already started to be two rules.
-        if (!Array.isArray(channels))
-            continue;
-        const unique = [
-            ...new Set(channels.filter((channel) => typeof channel === 'string' && channel.length > 0)),
-        ];
-        if (unique.length === 0)
-            continue;
-        pairs.push(`(${columns.connector} = ? AND ${columns.channel} IN (${unique.map(() => '?').join(', ')}))`);
-        params.push(connector, ...unique);
-    }
-    return pairs.length === 0 ? null : { sql: `(${pairs.join(' OR ')})`, params };
-}
-//# sourceMappingURL=channel-grant.js.map

package/dist/context-compile/compiler-policy.d.ts

@@ -1,39 +0,0 @@
-import type { ContextEvidence, ContextRef } from './types.js';
-import type { ContextCandidate, HiddenCandidateAggregate } from './source-readers.js';
-export interface ContextCompilerPolicyInput {
-    task: string;
-    candidates: ContextCandidate[];
-    hidden: HiddenCandidateAggregate;
-    limit?: number;
-    strictness?: 'recall' | 'balanced' | 'strict' | 'low' | 'medium' | 'high';
-    max_tokens?: number;
-}
-export interface ContextCompilerPolicyResult {
-    selected_evidence: ContextEvidence[];
-    source_refs: ContextRef[];
-    evidence_clusters: unknown[];
-    related_decisions: Array<{
-        memory_id: string;
-        title: string;
-    }>;
-    rejected_refs: ContextRef[];
-    rejected_summary: string[];
-    missing_context: string[];
-    caveats: string[];
-    retrieval_diagnostics: {
-        candidate_count: number;
-        selected_count: number;
-        rejected_count: number;
-        hidden: HiddenCandidateAggregate;
-        deduplicated_count: number;
-        strict_vector_only_rejected_count: number;
-        token_budget_rejected_count: number;
-        limit_rejected_count: number;
-        truncated_by_tokens: boolean;
-        estimated_tokens: number;
-    };
-    estimated_tokens: number;
-}
-export declare function estimateEvidenceTokens(evidence: Pick<ContextEvidence, 'title' | 'excerpt'>): number;
-export declare function applyContextCompilerPolicy(input: ContextCompilerPolicyInput): ContextCompilerPolicyResult;
-//# sourceMappingURL=compiler-policy.d.ts.map

package/dist/context-compile/compiler-policy.js

@@ -1,147 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.estimateEvidenceTokens = estimateEvidenceTokens;
-exports.applyContextCompilerPolicy = applyContextCompilerPolicy;
-const ref_js_1 = require("./ref.js");
-function normalizeLimit(limit) {
-    return Math.max(0, Math.min(100, Math.floor(limit ?? 10)));
-}
-function estimateEvidenceTokens(evidence) {
-    const text = `${evidence.title ?? ''}\n${evidence.excerpt ?? ''}`;
-    return Math.max(1, Math.ceil(text.length / 4));
-}
-function sortedCandidates(candidates) {
-    return [...candidates].sort((left, right) => {
-        const scoreDiff = right.score - left.score;
-        if (scoreDiff !== 0) {
-            return scoreDiff;
-        }
-        return (right.timestamp_ms ?? 0) - (left.timestamp_ms ?? 0);
-    });
-}
-function shouldRejectVectorOnly(candidate, strictness) {
-    return (strictness === 'strict' &&
-        candidate.support.is_vector_only === true &&
-        candidate.support.confirmation_signals.length === 0);
-}
-function evidenceFromCandidate(candidate) {
-    return {
-        ref: candidate.ref,
-        title: candidate.title,
-        excerpt: candidate.excerpt,
-        score: candidate.score,
-        reasons: [
-            ...(candidate.support.confirmation_signals ?? []),
-            ...(candidate.support.graph_expanded ? ['graph_expanded'] : []),
-        ],
-        ...(candidate.retrieval_diagnostics
-            ? { retrieval_diagnostics: candidate.retrieval_diagnostics }
-            : {}),
-    };
-}
-function addCountSummary(parts, label, count) {
-    if (count > 0) {
-        parts.push(`${label}: ${count}`);
-    }
-}
-function normalizeStrictness(strictness) {
-    switch (strictness) {
-        case 'low':
-        case 'recall':
-            return 'recall';
-        case 'high':
-        case 'strict':
-            return 'strict';
-        case 'medium':
-        case 'balanced':
-        case undefined:
-            return 'balanced';
-    }
-    return 'balanced';
-}
-function applyContextCompilerPolicy(input) {
-    const limit = normalizeLimit(input.limit);
-    const strictness = normalizeStrictness(input.strictness);
-    const maxTokens = typeof input.max_tokens === 'number' && Number.isFinite(input.max_tokens)
-        ? Math.max(0, Math.floor(input.max_tokens))
-        : null;
-    const seen = new Set();
-    const selected = [];
-    const sourceRefs = [];
-    const rejectedRefs = [];
-    const counters = {
-        deduplicated: 0,
-        strictVectorOnly: 0,
-        tokenBudget: 0,
-        limit: 0,
-    };
-    let estimatedTokens = 0;
-    for (const candidate of sortedCandidates(input.candidates)) {
-        if (!candidate.visible) {
-            continue;
-        }
-        const key = (0, ref_js_1.serializeContextRefForProvenance)(candidate.ref);
-        if (seen.has(key)) {
-            counters.deduplicated += 1;
-            rejectedRefs.push(candidate.ref);
-            continue;
-        }
-        if (shouldRejectVectorOnly(candidate, strictness)) {
-            counters.strictVectorOnly += 1;
-            rejectedRefs.push(candidate.ref);
-            continue;
-        }
-        if (selected.length >= limit) {
-            counters.limit += 1;
-            rejectedRefs.push(candidate.ref);
-            continue;
-        }
-        const evidence = evidenceFromCandidate(candidate);
-        const nextTokens = estimateEvidenceTokens(evidence);
-        if (maxTokens !== null && estimatedTokens + nextTokens > maxTokens) {
-            counters.tokenBudget += 1;
-            rejectedRefs.push(candidate.ref);
-            continue;
-        }
-        selected.push(evidence);
-        sourceRefs.push(candidate.ref);
-        seen.add(key);
-        estimatedTokens += nextTokens;
-    }
-    const rejectedSummary = [];
-    addCountSummary(rejectedSummary, 'deduplicated duplicate candidates', counters.deduplicated);
-    addCountSummary(rejectedSummary, 'strictness rejected vector-only candidates', counters.strictVectorOnly);
-    addCountSummary(rejectedSummary, 'token budget rejected candidates', counters.tokenBudget);
-    addCountSummary(rejectedSummary, 'limit rejected candidates', counters.limit);
-    const caveats = [];
-    if (input.hidden.total > 0) {
-        caveats.push(`hidden candidates omitted: ${input.hidden.total}`);
-    }
-    const relatedDecisions = selected.flatMap((evidence) => evidence.ref.kind === 'memory'
-        ? [{ memory_id: evidence.ref.id, title: evidence.title ?? evidence.ref.id }]
-        : []);
-    return {
-        selected_evidence: selected,
-        source_refs: sourceRefs,
-        evidence_clusters: [],
-        related_decisions: relatedDecisions,
-        rejected_refs: rejectedRefs,
-        rejected_summary: rejectedSummary,
-        missing_context: selected.length === 0 ? [`No visible evidence selected for task: ${input.task}`] : [],
-        caveats,
-        retrieval_diagnostics: {
-            candidate_count: input.candidates.length,
-            selected_count: selected.length,
-            rejected_count: rejectedRefs.length,
-            hidden: input.hidden,
-            deduplicated_count: counters.deduplicated,
-            strict_vector_only_rejected_count: counters.strictVectorOnly,
-            token_budget_rejected_count: counters.tokenBudget,
-            limit_rejected_count: counters.limit,
-            truncated_by_tokens: counters.tokenBudget > 0,
-            estimated_tokens: estimatedTokens,
-        },
-        estimated_tokens: estimatedTokens,
-    };
-}
-//# sourceMappingURL=compiler-policy.js.map

package/dist/context-compile/compiler.d.ts

@@ -1,18 +0,0 @@
-import type { DatabaseAdapter } from '../db-manager.js';
-import type { ContextBoundary, ContextCompileInput, ContextPacket, ContextRef } from './types.js';
-import { type ContextSourceReadInput, type ContextSourceReadResult } from './source-readers.js';
-type ContextCompilerAdapter = Pick<DatabaseAdapter, 'prepare'>;
-export interface ContextCompilerDeps {
-    adapter?: ContextCompilerAdapter;
-    boundary?: ContextBoundary;
-    signal?: AbortSignal;
-    deadlineMs?: number;
-    now?: () => number;
-    packetId?: () => string;
-    readMemoryCandidates?: (input: ContextSourceReadInput) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
-    readRawCandidates?: (input: ContextSourceReadInput) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
-    readGraphCandidates?: (input: ContextSourceReadInput, visibleRefs: readonly ContextRef[]) => Promise<ContextSourceReadResult> | ContextSourceReadResult;
-}
-export declare function compileContext(input: ContextCompileInput, deps?: ContextCompilerDeps): Promise<ContextPacket>;
-export {};
-//# sourceMappingURL=compiler.d.ts.map