@guanlin4924/devflow-pi 0.1.79 → 0.1.81

package/plugins/devflow-intel/skills/workflow-code-index/scripts/domain_registry.py

@@ -0,0 +1,168 @@
+"""Append-only project scoped mapping bundles, separate from code snapshots.
+
+Approval import is an explicit local reviewer attestation, not an authorization service.
+"""
+import json
+import sqlite3
+from datetime import datetime, timezone
+
+SCHEMA = '''
+CREATE TABLE IF NOT EXISTS domain_mapping_revisions(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,code_generation TEXT NOT NULL,
+ requirement_revision TEXT,status TEXT NOT NULL,previous_revision TEXT,bundle_json TEXT NOT NULL,
+ created_at TEXT NOT NULL,PRIMARY KEY(project_id,mapping_revision));
+CREATE TABLE IF NOT EXISTS domain_mapping_current(project_id TEXT PRIMARY KEY,current_revision TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS domain_term_versions(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,term_id TEXT NOT NULL,canonical_name TEXT NOT NULL,
+ PRIMARY KEY(project_id,mapping_revision,term_id));
+CREATE TABLE IF NOT EXISTS domain_term_alias_versions(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,term_id TEXT NOT NULL,alias TEXT NOT NULL,
+ PRIMARY KEY(project_id,mapping_revision,term_id,alias));
+CREATE TABLE IF NOT EXISTS domain_feature_versions(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,feature_id TEXT NOT NULL,canonical_name TEXT NOT NULL,
+ PRIMARY KEY(project_id,mapping_revision,feature_id));
+CREATE TABLE IF NOT EXISTS domain_feature_terms(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,feature_id TEXT NOT NULL,term_id TEXT NOT NULL,
+ PRIMARY KEY(project_id,mapping_revision,feature_id,term_id));
+CREATE TABLE IF NOT EXISTS domain_feature_bindings(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,feature_id TEXT NOT NULL,entity_id TEXT NOT NULL,
+ entity_version_id TEXT NOT NULL,code_generation TEXT NOT NULL,
+ PRIMARY KEY(project_id,mapping_revision,feature_id,entity_version_id));
+CREATE TABLE IF NOT EXISTS domain_mapping_decisions(
+ project_id TEXT NOT NULL,mapping_revision TEXT NOT NULL,reviewer TEXT NOT NULL,reason TEXT NOT NULL,
+ requirement_revision TEXT NOT NULL,decision TEXT NOT NULL,PRIMARY KEY(project_id,mapping_revision));
+'''
+
+
+def import_bundle(path, project, bundle, expected, code_conn, generation):
+    if not project or len(project) > 200:
+        raise ValueError('project_id required (max 200 characters)')
+    if not isinstance(bundle, dict) or len(json.dumps(bundle)) > 2_000_000:
+        raise ValueError('invalid or oversized mapping bundle')
+    revision = bundle.get('mapping_revision')
+    if not isinstance(revision, str) or not revision or len(revision) > 200:
+        raise ValueError('mapping_revision required (max 200 characters)')
+    if bundle.get('code_generation') != generation:
+        raise ValueError('mapping code_generation mismatch')
+    status = bundle.get('status', 'candidate')
+    if status not in {'candidate', 'pending_review', 'approved', 'rejected', 'historical_unmapped'}:
+        raise ValueError('invalid mapping lifecycle status')
+    decision = bundle.get('decision', {})
+    if status in {'approved', 'rejected'} and not all(isinstance(v, str) and v.strip() for v in [
+            decision.get('reviewer'), decision.get('reason'), bundle.get('requirement_revision')]):
+        raise ValueError('review decision requires reviewer, reason and requirement_revision')
+    terms = bundle.get('terms', [])
+    features = bundle.get('features', [])
+    if not terms or not features or len(terms) + len(features) > 1000:
+        raise ValueError('bundle requires 1..1000 terms and features')
+    term_ids = {term['id'] for term in terms}
+    feature_ids = {feature['id'] for feature in features}
+    if len(term_ids) != len(terms) or len(feature_ids) != len(features):
+        raise ValueError('duplicate term or feature id')
+    for feature in features:
+        if not set(feature.get('term_ids', [])).issubset(term_ids):
+            raise ValueError('unknown term reference')
+        for binding in feature.get('bindings', []):
+            row = code_conn.execute('SELECT entity_version_id,content_hash FROM entity_versions WHERE snapshot_id=? AND logical_id=?', (generation, binding['entity_id'])).fetchone()
+            if row is None or binding.get('entity_version_id') != row[0] or binding.get('content_hash') != row[1]:
+                raise ValueError('binding entity version or content hash mismatch')
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(path)
+    try:
+        conn.executescript(SCHEMA)
+        if 'decision' not in {row[1] for row in conn.execute('PRAGMA table_info(domain_mapping_decisions)')}:
+            conn.execute("ALTER TABLE domain_mapping_decisions ADD COLUMN decision TEXT NOT NULL DEFAULT 'approved'")
+        immutable_tables = ['domain_mapping_revisions', 'domain_term_versions', 'domain_term_alias_versions', 'domain_feature_versions', 'domain_feature_terms', 'domain_feature_bindings', 'domain_mapping_decisions']
+        for table in immutable_tables:
+            for operation in ['UPDATE','DELETE']:
+                conn.execute(f"CREATE TRIGGER IF NOT EXISTS immutable_{table}_{operation} BEFORE {operation} ON {table} BEGIN SELECT RAISE(ABORT, 'mapping revisions are append-only'); END")
+        revision_children = ['domain_term_versions', 'domain_term_alias_versions', 'domain_feature_versions', 'domain_feature_terms', 'domain_feature_bindings', 'domain_mapping_decisions']
+        for table in revision_children:
+            conn.execute(f'''CREATE TRIGGER IF NOT EXISTS sealed_{table}_insert BEFORE INSERT ON {table}
+              WHEN EXISTS(SELECT 1 FROM domain_mapping_revisions r
+                WHERE r.project_id=NEW.project_id AND r.mapping_revision=NEW.mapping_revision)
+              BEGIN SELECT RAISE(ABORT, 'mapping revision is sealed'); END''')
+        for operation in ['INSERT','UPDATE']:
+            conn.execute(f'''CREATE TRIGGER IF NOT EXISTS approved_current_{operation} BEFORE {operation} ON domain_mapping_current
+              WHEN NOT EXISTS(SELECT 1 FROM domain_mapping_revisions r JOIN domain_mapping_decisions d
+              ON d.project_id=r.project_id AND d.mapping_revision=r.mapping_revision
+              WHERE r.project_id=NEW.project_id AND r.mapping_revision=NEW.current_revision
+              AND r.status='approved' AND d.decision='approved' AND length(d.reviewer)>0 AND length(d.reason)>0)
+              BEGIN SELECT RAISE(ABORT, 'current must reference an approved revision with decision'); END''')
+        conn.commit()
+        conn.execute('BEGIN IMMEDIATE')
+        current = conn.execute('SELECT current_revision FROM domain_mapping_current WHERE project_id=?', (project,)).fetchone()
+        if (current[0] if current else None) != expected:
+            raise ValueError('mapping current CAS conflict')
+        previous = bundle.get('previous_revision')
+        if previous:
+            prior = conn.execute('SELECT status,bundle_json FROM domain_mapping_revisions WHERE project_id=? AND mapping_revision=?', (project,previous)).fetchone()
+            if prior is None:
+                raise ValueError('previous mapping revision does not exist in project')
+            transitions = {'candidate': {'candidate','pending_review','rejected','historical_unmapped'}, 'pending_review': {'approved','rejected','candidate'}, 'approved': {'candidate','historical_unmapped'}, 'rejected': {'candidate'}, 'historical_unmapped': {'candidate'}}
+            if status not in transitions[prior[0]]:
+                raise ValueError('invalid mapping status transition')
+            if status == 'approved':
+                prior_bundle = json.loads(prior[1])
+                for field in ['terms','features','code_generation','requirement_revision']:
+                    if bundle.get(field) != prior_bundle.get(field):
+                        raise ValueError('approved mapping differs from pending review bundle')
+        elif status not in {'candidate','historical_unmapped'}:
+            raise ValueError('review states require a previous mapping revision')
+        for term in terms:
+            conn.execute('INSERT INTO domain_term_versions VALUES(?,?,?,?)', (project,revision,term['id'],term['name']))
+            for alias in set(term.get('aliases', [])):
+                conn.execute('INSERT INTO domain_term_alias_versions VALUES(?,?,?,?)', (project,revision,term['id'],alias))
+        for feature in features:
+            conn.execute('INSERT INTO domain_feature_versions VALUES(?,?,?,?)', (project,revision,feature['id'],feature['name']))
+            for term in feature.get('term_ids', []):
+                conn.execute('INSERT INTO domain_feature_terms VALUES(?,?,?,?)', (project,revision,feature['id'],term))
+            for binding in feature.get('bindings', []):
+                conn.execute('INSERT INTO domain_feature_bindings VALUES(?,?,?,?,?,?)', (project,revision,feature['id'],binding['entity_id'],binding['entity_version_id'],generation))
+        if status in {'approved','rejected'}:
+            conn.execute('INSERT INTO domain_mapping_decisions VALUES(?,?,?,?,?,?)', (project,revision,decision['reviewer'],decision['reason'],bundle['requirement_revision'],status))
+        # The revision row is the seal: child rows are staged first in this
+        # transaction and no child INSERT is allowed after the seal exists.
+        conn.execute('INSERT INTO domain_mapping_revisions VALUES(?,?,?,?,?,?,?,?)', (
+            project,revision,generation,bundle.get('requirement_revision'),status,previous,
+            json.dumps(bundle, ensure_ascii=False, sort_keys=True),datetime.now(timezone.utc).isoformat()))
+        if status == 'approved':
+            conn.execute('INSERT INTO domain_mapping_current VALUES(?,?) ON CONFLICT(project_id) DO UPDATE SET current_revision=excluded.current_revision', (project,revision))
+        conn.commit()
+    finally:
+        conn.close()
+    return {'mapping_revision': revision, 'status': status, 'project_id': project}
+
+
+def resolve(path, project, terms, generation, revision='approved-current', statuses=None, requirement=None):
+    if not path.is_file():
+        return {'status': 'capability_unavailable', 'mappings': [], 'mapping_revision': None}
+    statuses = statuses or ['approved']
+    if not set(statuses).issubset({'approved', 'candidate', 'pending_review', 'rejected', 'historical_unmapped'}):
+        raise ValueError('invalid mapping statusFilter')
+    conn = sqlite3.connect(path.as_uri() + '?mode=ro', uri=True)
+    conn.row_factory = sqlite3.Row
+    try:
+        conn.execute('BEGIN')
+        if revision == 'approved-current':
+            row = conn.execute('SELECT current_revision FROM domain_mapping_current WHERE project_id=?', (project,)).fetchone()
+            revision = row[0] if row else None
+        row = conn.execute('SELECT * FROM domain_mapping_revisions WHERE project_id=? AND mapping_revision=?', (project,revision)).fetchone()
+        result = {'status': 'no_domain_match', 'mapping_revision': revision, 'mappings': [], 'requirement_revision': row['requirement_revision'] if row else None}
+        if row is None or row['status'] not in statuses:
+            return result
+        if requirement and requirement != row['requirement_revision']:
+            raise ValueError('requirement revision mismatch')
+        if row['code_generation'] != generation:
+            result['status'] = 'mapping_snapshot_mismatch'
+            return result
+        bundle = json.loads(row['bundle_json'])
+        requested = {term.casefold() for term in terms}
+        matched = {term['id'] for term in bundle['terms'] if requested.intersection(value.casefold() for value in [term['name'], *term.get('aliases', [])])}
+        result['mappings'] = [{**feature, 'mapping_status': row['status'], 'mapping_revision': revision, 'code_generation': generation,
+                               'provenance': {'source_type': 'reviewer_attestation' if row['status'] == 'approved' else 'candidate_import', 'decision': bundle.get('decision')}}
+                              for feature in bundle['features'] if matched.intersection(feature.get('term_ids', []))]
+        result['status'] = 'ambiguous' if len(result['mappings']) > 1 else 'ok' if result['mappings'] else 'no_domain_match'
+        return result
+    finally:
+        conn.close()

package/plugins/devflow-intel/skills/workflow-code-index/scripts/hybrid_query.py

@@ -0,0 +1,367 @@
+"""Bounded structured query executor; callers never supply SQL."""
+import json
+import re
+import sqlite3
+import time
+from pathlib import PurePosixPath
+from adapters.capabilities import confidence_for_parser
+from source_content import verify_span
+from domain_registry import resolve
+
+PHASES = ['resolve_domain', 'search_symbols', 'search_content', 'rank_seeds', 'traverse_relations', 'impact_change', 'verify_evidence', 'compose_result']
+FIELDS = {'codeGeneration','mappingRevision','requirementRevision','featureTerms','identifiers','repositoryFilter','pathPrefix','phases','operations','seedEntityIds','changeType','coveragePolicy','direction','depth','limit','statusFilter','includeHeuristic','language','matchKind'}
+CHANGES = {'remove_field','rename_field','change_type','optional_to_required','required_to_optional','change_nullability','change_enum'}
+
+
+def validate_plan(plan):
+    if not isinstance(plan, dict) or set(plan) - FIELDS:
+        raise ValueError('QueryPlan contains unknown fields')
+    plan = dict(plan)
+    phases = plan.get('phases', plan.get('operations', ['resolve_domain', 'search_symbols', 'search_content', 'rank_seeds', 'verify_evidence', 'compose_result']))
+    if not isinstance(phases, list) or any(p not in PHASES for p in phases) or len(phases) != len(set(phases)):
+        raise ValueError('invalid query phases')
+    plan['phases'] = [p for p in PHASES if p in phases]
+    for key in ['featureTerms', 'identifiers', 'seedEntityIds', 'repositoryFilter', 'statusFilter']:
+        value = plan.get(key, ['approved'] if key == 'statusFilter' else [])
+        maximum = 16 if key != 'seedEntityIds' else 20
+        if not isinstance(value, list) or len(value) > maximum or any(not isinstance(v, str) or not v or len(v) > (1000 if key == 'seedEntityIds' else 256) or '\x00' in v for v in value):
+            raise ValueError('invalid or oversized ' + key)
+        plan[key] = value
+    for key, default, maximum in [('limit', 20, 100), ('depth', 2, 5)]:
+        value = plan.get(key, default)
+        if type(value) is not int or not 0 <= value <= maximum or key == 'limit' and value == 0:
+            raise ValueError('invalid ' + key)
+        plan[key] = value
+    prefix = plan.get('pathPrefix', '')
+    if not isinstance(prefix, str) or len(prefix) > 1000 or '\\' in prefix or '\x00' in prefix or PurePosixPath(prefix).is_absolute() or '..' in PurePosixPath(prefix).parts:
+        raise ValueError('pathPrefix must be a repository-relative path without traversal')
+    plan['pathPrefix'] = prefix.strip('/')
+    if plan.get('direction', 'outgoing') not in {'incoming','outgoing','both'}:
+        raise ValueError('invalid direction')
+    if plan.get('changeType') is not None and plan['changeType'] not in CHANGES:
+        raise ValueError('invalid changeType')
+    if 'impact_change' in phases and plan.get('changeType') not in CHANGES:
+        raise ValueError('impact_change requires changeType')
+    if plan.get('coveragePolicy', 'local_only') != 'local_only':
+        raise ValueError('only local_only coverage is supported')
+    if plan.get('matchKind', 'literal') not in {'literal','substring','identifier','exact_phrase'}:
+        raise ValueError('invalid matchKind')
+    if plan.get('language') is not None and (not isinstance(plan['language'], str) or len(plan['language']) > 80):
+        raise ValueError('invalid language')
+    if not set(plan['statusFilter']).issubset({'approved','candidate','pending_review','rejected','historical_unmapped'}):
+        raise ValueError('invalid statusFilter')
+    search = bool({'search_symbols','search_content'}.intersection(phases))
+    domain = 'resolve_domain' in phases
+    has_seed = bool(plan['seedEntityIds'])
+    if not phases:
+        raise ValueError('QueryPlan requires at least one phase')
+    if 'rank_seeds' in phases and not (search or domain or has_seed):
+        raise ValueError('rank_seeds requires search, domain resolution or explicit seeds')
+    if {'traverse_relations','impact_change'}.intersection(phases) and not (has_seed or domain or (search and 'rank_seeds' in phases)):
+        raise ValueError('traversal requires explicit seeds, resolve_domain, or search + rank_seeds')
+    if 'verify_evidence' in phases and not (search or domain or {'traverse_relations','impact_change'}.intersection(phases)):
+        raise ValueError('verify_evidence requires a result-producing phase')
+    if phases == ['compose_result']:
+        raise ValueError('compose_result requires a result-producing phase')
+    return plan
+
+
+def read_connection(path):
+    conn = sqlite3.connect(path.as_uri() + '?mode=ro&immutable=1', uri=True)
+    conn.row_factory = sqlite3.Row
+    conn.execute('PRAGMA query_only=ON')
+    deadline = time.monotonic() + 3
+    conn.set_progress_handler(lambda: int(time.monotonic() > deadline), 1000)
+    conn.execute('BEGIN')
+    return conn
+
+
+def _scope(plan, snapshot):
+    scope = snapshot.get('workspace', {}).get('scanScope', {})
+    repos = scope.get('codebases', [])
+    known = {r['name']: r for r in repos}
+    if plan['repositoryFilter'] and (not known or not set(plan['repositoryFilter']).issubset(known)):
+        raise ValueError('repositoryFilter is outside snapshot scan scope')
+    prefixes = []
+    selected = plan['repositoryFilter'] or ([r['name'] for r in repos] if plan['pathPrefix'] else [])
+    for name in selected:
+        base = known[name].get('workspacePath', '')
+        prefix = '/'.join(p for p in [base.strip('/'), plan['pathPrefix']] if p and p != '.')
+        prefixes.append((name, prefix))
+    if not prefixes:
+        prefixes = [(None, plan['pathPrefix'])]
+    return prefixes
+
+
+def _where(plan, prefixes, alias='s'):
+    parts, args = [], []
+    for repository, prefix in prefixes:
+        p, values = [], []
+        if repository:
+            p.append(f'{alias}.codebase=?'); values.append(repository)
+        if prefix:
+            p.append(f'({alias}.path=? OR substr({alias}.path,1,?)=?)')
+            values.extend([prefix, len(prefix) + 1, prefix + '/'])
+        parts.append('(' + (' AND '.join(p) or '1') + ')'); args.extend(values)
+    where = '(' + ' OR '.join(parts) + ')'
+    if plan.get('language'):
+        where += f' AND {alias}.language=?'; args.append(plan['language'])
+    return where, args
+
+
+def _decorate(item, generation, kind):
+    item['snapshot'] = generation
+    item['entity_id'] = (item.get('id') or item.get('entity_id')) if kind == 'symbol' else item.get('entity_id')
+    item['entity_version_id'] = generation + ':' + item['entity_id'] if item.get('entity_id') else None
+    item['parser'] = item.get('parser') or 'unknown'
+    item['confidence'] = item.get('confidence') or ('exact' if kind == 'content' else confidence_for_parser(item['parser'], 'symbol'))
+    item['result_type'] = kind
+    item['provenance'] = {'relation_parser': item.get('relation_parser'), 'source_file_parser': item.get('source_file_parser', item['parser']), 'source': 'snapshot_source' if kind == 'content' else 'code_index', 'snapshot': generation, 'parser': item['parser'], 'content_hash': item.get('content_hash')}
+    return item
+
+
+def execute(conn, snapshot, plan, registry_path, project):
+    plan = validate_plan(plan)
+    generation = snapshot['generation']
+    phases = plan['phases']; limit = plan['limit']; prefixes = _scope(plan, snapshot)
+    tables = {r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    terms = list(dict.fromkeys([*plan['featureTerms'], *plan['identifiers']]))
+    conn.create_function('identifier_match', 2, lambda content, term: int(bool(re.search(r'(?<!\w)' + re.escape(term) + r'(?!\w)', content))), deterministic=True)
+    results, phase_status, seeds = {}, {}, set(plan['seedEntityIds'])
+    truncated = False
+    mappings = {'mapping_revision': None, 'requirement_revision': None, 'mappings': []}
+    if 'resolve_domain' in phases:
+        if not project:
+            raise ValueError('resolve_domain requires project_id')
+        mappings = resolve(registry_path, project, terms, generation, plan.get('mappingRevision', 'approved-current'), plan['statusFilter'], plan.get('requirementRevision'))
+        phase_status['resolve_domain'] = mappings['status']
+        if mappings['status'] == 'ok':
+            for feature in mappings['mappings']:
+                # Candidate mapping is visible but never silently becomes a traversal seed.
+                if feature['mapping_status'] == 'approved':
+                    seeds.update(binding['entity_id'] for binding in feature.get('bindings', []))
+    where, scope_args = _where(plan, prefixes)
+    for seed in sorted(seeds)[:20]:
+        row = conn.execute(f'SELECT s.* FROM symbols s WHERE {where} AND s.id=?', (*scope_args,seed)).fetchone()
+        if row and any(seed == binding['entity_id'] for feature in mappings['mappings'] for binding in feature.get('bindings', [])):
+            item = _decorate(dict(row), generation, 'symbol')
+            item.update(match_kind='approved_domain_binding', score=100, matched_terms=terms, score_contributions=[{'kind':'approved_domain_binding','score':100,'reason':'approved domain feature bound to this entity version'}])
+            results[('symbol',item['id'])] = item
+    if 'search_symbols' in phases:
+        count = 0
+        for term in terms:
+            rows = conn.execute(f'''SELECT s.* FROM symbols s WHERE {where}
+              AND (instr(lower(s.name),lower(?))>0 OR instr(lower(s.qualified_name),lower(?))>0 OR instr(lower(s.path),lower(?))>0)
+              ORDER BY CASE WHEN lower(s.name)=lower(?) THEN 0
+                            WHEN instr(lower(s.name),lower(?))>0 OR instr(lower(s.qualified_name),lower(?))>0 THEN 1
+                            ELSE 2 END, s.path,s.line_start,s.id LIMIT ?''',
+              (*scope_args,term,term,term,term,term,term,limit + 1)).fetchall()
+            truncated |= len(rows) > limit
+            for row in rows[:limit]:
+                item = _decorate(dict(row), generation, 'symbol')
+                if item['name'].casefold() == term.casefold() and term in plan['identifiers']:
+                    kind, score = 'identifier_exact', 90
+                elif item['name'].casefold() == term.casefold():
+                    kind, score = 'symbol_exact', 80
+                elif term.casefold() in item['name'].casefold() or term.casefold() in (item.get('qualified_name') or '').casefold():
+                    kind, score = 'symbol_substring', 60
+                else:
+                    kind, score = 'path_match', 50
+                item['match_kind'] = kind
+                item['score'] = score
+                item['score_contributions'] = [{'kind':kind,'term':term,'score':score,'reason':'literal match against indexed symbol or path'}]
+                item['matched_terms'] = [term]
+                key = ('symbol', item['id'])
+                if key in results:
+                    results[key]['matched_terms'].append(term)
+                    results[key]['score'] = max(results[key]['score'], item['score'])
+                    results[key]['score_contributions'].extend(item['score_contributions'])
+                else:
+                    results[key] = item
+                count += 1
+        phase_status['search_symbols'] = 'ok' if count else 'no_symbol_match'
+    if 'search_content' in phases:
+        if 'source_content_chunks' not in tables:
+            phase_status['search_content'] = 'capability_unavailable'
+        else:
+            count = 0
+            for term in terms:
+                fts = 'source_content_fts' in tables and len(term) >= 3
+                match = ' AND c.rowid IN (SELECT rowid FROM source_content_fts WHERE source_content_fts MATCH ?)' if fts else ''
+                identifier = ' AND identifier_match(c.content,?)=1' if plan.get('matchKind') == 'identifier' else ''
+                params = [*scope_args, term]
+                if identifier:
+                    params.append(term)
+                if fts:
+                    params.append('"' + term.replace('"', '""') + '"')
+                rows = conn.execute(f'SELECT c.*,s.codebase,s.parser FROM source_content_chunks c JOIN code_files s ON s.id=c.code_file_id WHERE {where} AND instr(c.content,?)>0{identifier}{match} ORDER BY c.path,c.chunk_no LIMIT ?', (*params,limit + 1)).fetchall()
+                truncated |= len(rows) > limit
+                for row in rows[:limit]:
+                    item = dict(row)
+                    position = re.search(r'(?<!\w)' + re.escape(term) + r'(?!\w)', item['content']).start() if identifier else item['content'].find(term)
+                    before = item['content'][:position]
+                    item['line_start'] += before.count('\n')
+                    item['line_end'] = item['line_start'] + term.count('\n')
+                    item['matchedText'] = term
+                    item.pop('content', None)
+                    owner = conn.execute('''SELECT id FROM symbols
+                      WHERE codebase=? AND path=? AND line_start<=? AND line_end>=? AND kind<>?
+                      ORDER BY line_end-line_start,id LIMIT 1''',
+                      (item['codebase'],item['path'],item['line_start'],item['line_start'],'file')).fetchone()
+                    if owner:
+                        item['entity_id'] = owner[0]
+                    else:
+                        # File-level content (constants/configuration outside a
+                        # symbol) still needs a stable snapshot-bound identity.
+                        item['entity_id'] = item['code_file_id']
+                    item = _decorate(item, generation, 'content')
+                    item['match_kind'] = plan.get('matchKind', 'literal')
+                    item['score'] = 40
+                    item['score_contributions'] = [{'kind':'content_' + item['match_kind'],'term':term,'score':40,'reason':'literal occurrence in immutable source chunk'}]
+                    results[('content', item['chunk_id'], term)] = item
+                    count += 1
+            phase_status['search_content'] = 'ok' if count else 'no_content_match'
+    ranked = sorted(results.values(), key=lambda x: (-x['score'], x['path'], x['line_start']))
+    if 'rank_seeds' in phases:
+        seeds.update(item['id'] for item in ranked if item['result_type'] == 'symbol' and item.get('kind') != 'file')
+        for item in ranked:
+            if item['result_type'] == 'content':
+                rows = conn.execute('SELECT id FROM symbols WHERE codebase=? AND path=? AND line_start<=? AND line_end>=? AND kind<>? ORDER BY line_end-line_start,id LIMIT 2', (item['codebase'],item['path'],item['line_start'],item['line_start'],'file')).fetchall()
+                seeds.update(row[0] for row in rows)
+    # Validate and scope every explicit, domain, and traversal seed against the pinned index.
+    valid_seeds = []
+    for seed in sorted(seeds):
+        if 'impact_change' in phases and 'entity_versions' in tables:
+            row = conn.execute(f'SELECT e.logical_id FROM entity_versions e JOIN code_files s ON s.path=e.path AND s.codebase=e.codebase WHERE {where} AND e.logical_id=? AND e.snapshot_id=?', (*scope_args, seed, generation)).fetchone()
+        else:
+            row = conn.execute(f'SELECT s.id FROM symbols s WHERE {where} AND s.id=?', (*scope_args, seed)).fetchone()
+        if row:
+            valid_seeds.append(seed)
+    truncated |= len(valid_seeds) > 20
+    valid_seeds = valid_seeds[:20]
+    edges = []
+    for phase in ['traverse_relations','impact_change']:
+        if phase not in phases:
+            continue
+        table = 'relations' if phase == 'traverse_relations' else 'semantic_flows'
+        if table not in tables:
+            phase_status[phase] = 'capability_unavailable'; continue
+        if mappings.get('status') == 'ambiguous' and not plan['seedEntityIds']:
+            phase_status[phase] = 'ambiguous'; continue
+        frontier = list(valid_seeds); visited = set(frontier); seen_edges = set()
+        before_count = len(edges)
+        for depth in range(1, plan['depth'] + 1):
+            next_frontier = []
+            for seed in frontier:
+                source, target = ('from_id','to_id') if table == 'relations' else ('source_id','target_id')
+                direction = plan.get('direction','outgoing')
+                condition = f'{source}=?' if direction == 'outgoing' else f'{target}=?' if direction == 'incoming' else f'({source}=? OR {target}=?)'
+                args = [seed,seed] if direction == 'both' else [seed]
+                if not plan.get('includeHeuristic', False):
+                    condition += " AND confidence <> 'heuristic'"
+                rows = conn.execute(f'SELECT rowid AS _edge_rowid,* FROM {table} WHERE {condition} ORDER BY rowid LIMIT 102', args).fetchall()
+                truncated |= len(rows) > 100
+                for row in rows[:100]:
+                    item = dict(row)
+                    key = (table, item.pop('_edge_rowid'))
+                    if key in seen_edges:
+                        continue
+                    seen_edges.add(key)
+                    path = item.get('evidence_path') or item.get('source_path')
+                    if table == 'relations':
+                        owner = conn.execute('SELECT codebase FROM symbols WHERE id=?', (item[source],)).fetchone()
+                    else:
+                        owner = conn.execute('SELECT codebase FROM entity_versions WHERE snapshot_id=? AND logical_id=?', (generation,item[source])).fetchone()
+                    if not owner:
+                        continue
+                    file = conn.execute(f'SELECT s.parser,s.content_hash FROM code_files s WHERE {where} AND s.codebase=? AND s.path=?', (*scope_args,owner[0],path)).fetchone()
+                    if not file:
+                        continue
+                    item['relation_parser'] = item.get('parser') or item.get('extractor') or 'unknown'
+                    item['source_file_parser'] = file['parser']
+                    item['content_hash'] = file['content_hash']
+                    item['parser'] = item['relation_parser']
+                    item.update(path=path, depth=depth, line_start=item.get('evidence_line') or item.get('line_start'), result_type=phase)
+                    item = _decorate(item, generation, phase)
+                    if phase == 'impact_change':
+                        item['impact_kind'] = plan['changeType']
+                    edges.append(item)
+                    node = item[target] if item[source] == seed else item[source]
+                    if node and node not in visited:
+                        if table == 'relations':
+                            scoped_node = conn.execute(f'SELECT s.id FROM symbols s WHERE {where} AND s.id=?', (*scope_args,node)).fetchone()
+                        else:
+                            scoped_node = conn.execute(f'SELECT e.logical_id FROM entity_versions e JOIN code_files s ON s.path=e.path AND s.codebase=e.codebase WHERE {where} AND e.logical_id=? AND e.snapshot_id=?', (*scope_args,node,generation)).fetchone()
+                        if scoped_node:
+                            visited.add(node); next_frontier.append(node)
+                    if len(edges) >= limit:
+                        truncated = True; break
+                if len(edges) >= limit:
+                    break
+            frontier = next_frontier
+            if not frontier or len(edges) >= limit:
+                break
+        phase_status[phase] = 'ok' if len(edges) > before_count else 'no_index_evidence'
+    if 'verify_evidence' in phases:
+        for item in [*ranked, *edges]:
+            if 'source_artifacts' in tables:
+                verify_span(conn, item)
+            else:
+                item['evidence_status'] = 'evidence_unavailable'
+    raw_combined = [*ranked, *edges]
+    combined, by_entity = [], {}
+    for item in raw_combined:
+        version = item.get('entity_version_id')
+        if not version:
+            combined.append(item)
+            continue
+        evidence = {key: item.get(key) for key in ('result_type','match_kind','path','line_start','line_end','matchedText','content_hash','score','evidence_status') if item.get(key) is not None}
+        if version not in by_entity:
+            item['evidence_sources'] = [evidence]
+            by_entity[version] = item
+            combined.append(item)
+            continue
+        primary = by_entity[version]
+        primary['evidence_sources'].append(evidence)
+        primary['score_contributions'] = [*primary.get('score_contributions', []), *item.get('score_contributions', [])]
+        primary['matched_terms'] = list(dict.fromkeys([*primary.get('matched_terms', []), *item.get('matched_terms', [])]))
+        if item.get('score', 0) > primary.get('score', 0):
+            position = combined.index(primary)
+            item['evidence_sources'] = primary['evidence_sources']
+            item['score_contributions'] = primary['score_contributions']
+            item['matched_terms'] = primary['matched_terms']
+            combined[position] = item
+            by_entity[version] = item
+    combined.sort(key=lambda x: (-x.get('score', 0), x.get('path') or '', x.get('line_start') or 0))
+    truncated |= len(combined) > limit
+    status = 'ok' if combined else 'no_index_evidence'
+    if ranked and all(r['result_type'] == 'content' for r in ranked) and not edges:
+        status = 'content_match_only'
+    if not combined and len(phase_status) == 1:
+        status = next(iter(phase_status.values()))
+    if any(value == 'capability_unavailable' for value in phase_status.values()):
+        status = 'partial' if combined else 'capability_unavailable'
+    if truncated:
+        status = 'partial'
+    if mappings.get('status') == 'ambiguous':
+        status = 'ambiguous'
+    if any(item.get('evidence_status') == 'evidence_unavailable' or any(source.get('evidence_status') == 'evidence_unavailable' for source in item.get('evidence_sources', [])) for item in combined[:limit]):
+        status = 'evidence_unavailable'
+    coverage = {'policy': 'local_only','status': 'not_assessed'}
+    if 'impact_change' in phases and 'coverage_metrics' in tables:
+        coverage_row = conn.execute('SELECT * FROM coverage_metrics WHERE snapshot_id=?', (generation,)).fetchone()
+        if coverage_row:
+            coverage = dict(coverage_row)
+            coverage['policy'] = 'local_only'
+            coverage['status'] = 'partial' if coverage.get('files_parsed', 0) < coverage.get('files_scanned', 0) or coverage.get('dynamic_limitations', 0) else 'complete'
+            if coverage['status'] == 'partial' and status == 'ok':
+                status = 'partial'
+    # Revision consistency outranks result/evidence availability: callers must
+    # never mistake code hits for facts from an incompatible mapping snapshot.
+    if mappings.get('status') == 'mapping_snapshot_mismatch':
+        status = 'mapping_snapshot_mismatch'
+    return {'results': combined[:limit], 'mappings': mappings['mappings'], '_meta': {
+        'status': status,'snapshot': generation,'mapping_revision': mappings.get('mapping_revision'),
+        'requirement_revision': mappings.get('requirement_revision'), 'scope_hash': snapshot.get('workspace', {}).get('scopeHash'),
+        'phases': phase_status,'seedEntityIds': valid_seeds,'truncated': truncated,'planSchemaVersion': 1,
+        'coverage': coverage, 'resolvedPlan': {**plan,'codeGeneration': generation,'mappingRevision': mappings.get('mapping_revision')}}}

package/plugins/devflow-intel/skills/workflow-code-index/scripts/source_content.py

@@ -0,0 +1,88 @@
+"""Snapshot-owned source evidence. No query reads the live working tree."""
+import hashlib
+import json
+import sqlite3
+from pathlib import Path
+
+
+def digest(data):
+    return 'sha256:' + hashlib.sha256(data).hexdigest()
+
+
+def build_content(conn, root, files, generation, scope):
+    conn.executescript('''
+    CREATE TABLE snapshot_metadata(key TEXT PRIMARY KEY, value TEXT NOT NULL);
+    CREATE TABLE source_artifacts(content_hash TEXT PRIMARY KEY, content BLOB NOT NULL);
+    CREATE TABLE source_content_chunks(
+      chunk_id TEXT PRIMARY KEY, code_generation TEXT NOT NULL, code_file_id TEXT NOT NULL,
+      path TEXT NOT NULL, language TEXT NOT NULL, chunk_no INTEGER NOT NULL,
+      line_start INTEGER NOT NULL, line_end INTEGER NOT NULL, byte_start INTEGER NOT NULL,
+      byte_end INTEGER NOT NULL, content_hash TEXT NOT NULL, content TEXT NOT NULL);
+    CREATE INDEX source_chunks_file ON source_content_chunks(code_file_id, line_start);
+    ''')
+    mode = 'trigram'
+    try:
+        conn.execute("CREATE VIRTUAL TABLE source_content_fts USING fts5(content, content='source_content_chunks', content_rowid='rowid', tokenize='trigram')")
+    except sqlite3.OperationalError:
+        mode = 'bounded_literal_scan'
+    for record in files:
+        data = (Path(root) / record['path']).read_bytes()
+        if digest(data) != record['content_hash']:
+            raise ValueError('source changed during snapshot build: ' + record['path'])
+        conn.execute('INSERT OR IGNORE INTO source_artifacts VALUES(?,?)', (record['content_hash'], data))
+        lines = data.splitlines(keepends=True)
+        offset = 0
+        for number, start in enumerate(range(0, len(lines), 80)):
+            chunk = b''.join(lines[start:start + 80])
+            conn.execute('INSERT INTO source_content_chunks VALUES(?,?,?,?,?,?,?,?,?,?,?,?)', (
+                generation + ':' + record['id'] + ':' + str(number), generation, record['id'],
+                record['path'], record['language'], number, start + 1, min(start + 80, len(lines)),
+                offset, offset + len(chunk), record['content_hash'], chunk.decode('utf-8', errors='replace')))
+            offset += len(chunk)
+    if mode == 'trigram':
+        conn.execute("INSERT INTO source_content_fts(source_content_fts) VALUES('rebuild')")
+        conn.execute("INSERT INTO source_content_fts(source_content_fts, rank) VALUES('integrity-check', 1)")
+    capability = {'version': 1, 'tokenizer': mode, 'shortTerms': 'bounded_literal_scan', 'historicalEvidence': True}
+    conn.executemany('INSERT INTO snapshot_metadata VALUES(?,?)', [
+        ('scanScope', json.dumps(scope, sort_keys=True)), ('contentSearch', json.dumps(capability))])
+    conn.commit()  # Flush FTS pending segments before fingerprinting its immutable shadow tables.
+    conn.execute('INSERT INTO snapshot_metadata VALUES(?,?)', ('contentIntegrity', json.dumps(content_integrity(conn), sort_keys=True)))
+    return capability
+
+
+def verify_span(conn, item):
+    row = conn.execute('SELECT content FROM source_artifacts WHERE content_hash=?', (item.get('content_hash'),)).fetchone()
+    if row is None or digest(row[0]) != item.get('content_hash'):
+        item['evidence_status'] = 'evidence_unavailable'
+        return item
+    lines = row[0].decode('utf-8', errors='replace').splitlines()
+    start = max(1, item.get('line_start') or item.get('evidence_line') or 1)
+    end = min(item.get('line_end') or start, start + 19)
+    item['evidence'] = '\n'.join(lines[start - 1:end])[:4000]
+    item['evidence_status'] = 'verified'
+    return item
+
+
+def content_integrity(conn):
+    """Fingerprint the build-time integrity-checked source/FTS projection without writes."""
+    tables = {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+    checks = {}
+    for table in ['source_content_chunks', 'source_content_fts_data', 'source_content_fts_idx', 'source_content_fts_docsize', 'source_content_fts_config']:
+        if table not in tables:
+            continue
+        checksum = hashlib.sha256()
+        count = 0
+        for row in conn.execute(f'SELECT * FROM {table} ORDER BY 1,2'):
+            for value in row:
+                data = value if isinstance(value, bytes) else str(value).encode('utf-8')
+                checksum.update(len(data).to_bytes(8, 'big')); checksum.update(data)
+            count += 1
+        checks[table] = {'count': count, 'sha256': checksum.hexdigest()}
+    rowids = hashlib.sha256()
+    for row in conn.execute('SELECT rowid FROM source_content_chunks ORDER BY rowid'):
+        rowids.update(str(row[0]).encode() + b'\0')
+    checks['chunk_rowids'] = rowids.hexdigest()
+    if 'source_content_fts_docsize' in tables:
+        invalid = conn.execute('SELECT count(*) FROM source_content_chunks c LEFT JOIN source_content_fts_docsize f ON f.id=c.rowid WHERE f.id IS NULL').fetchone()[0]
+        checks['missing_fts_rowids'] = invalid
+    return checks